u1s1-cli 0.17.0 → 0.19.0

package/dist/agent-setup.js

@@ -328,14 +328,21 @@ First decide whether this task really needs a workflow. Good fit: many independe
 
 If it is a fit:
 
-1. Decompose the task, then write a JavaScript orchestration script. Top-level await and return are allowed. The script runs in a sandbox where ONLY these are available:
+0. **Prefer a built-in template** when one matches — call \`run_workflow\` with \`template\` + \`input\` instead of writing a script:
+   - \`i18n\` — translate locale file(s) to N languages: { "langs": ["en", "ja"], "source": "src/locales/zh.json" }
+   - \`review\` — per-file review + adversarial verification: { "files": [...] } or omit for git-diff files
+   - \`research\` — parallel investigation + synthesis: { "questions": ["..."], "context": "..." }
+   - \`refactor\` — rule-first batch refactor in isolated worktrees: { "instruction": "...", "files": [...] }
+1. Otherwise decompose the task and write a JavaScript orchestration script. Top-level await and return are allowed. The script runs in a sandbox where ONLY these are available:
    - \`subagent(task)\` or \`subagent({ task, model })\` — runs one sub-agent, resolves to its final output text
    - \`parallel([() => ..., ...])\` — concurrent fan-out; each thunk's error becomes \`null\`; barrier semantics
    - \`pipeline(items, [stage1, stage2, ...])\` — each item flows through all stages independently (prefer over parallel)
+   - \`judge(question)\` — cheap tool-free model call returning true/false; use for loop-until-done checks
+   - \`subagent({ task, worktree: true })\` — run in an isolated temp git worktree (auto-cleaned) when tasks would write conflicting files
    - \`log(...)\`, \`setTimeout/clearTimeout\`, standard JS builtins (Promise/JSON/Math/...)
    - NO require/import/process/fetch/fs access — the static validator rejects scripts that try
 2. Every task string must be fully self-contained: which files to read/write, what "done" means, how to self-verify.
-3. Call the \`run_workflow\` tool with the full source as \`script\`. Read its report carefully; on failures fix the script, or rerun with \`script_path\` + \`resume: true\` to continue from saved progress.
+3. Call the \`run_workflow\` tool with the full source as \`script\`. Read its report carefully; on failures fix the script, or rerun with \`script_path\` + \`resume: true\` to continue from saved progress. For workflows worth rerunning (e.g. recurring i18n syncs), pass a memorable \`save_as\` name — rerun later with just \`script_path\`.
 
 Keep scripts deterministic (same order of subagent calls every run) so resume works. Summarize the outcome to the user afterwards in their language.
 `;

package/dist/subagent.d.ts

@@ -15,10 +15,20 @@ export interface SubagentOptions {
     model?: string;
     timeoutMs?: number;
     signal?: AbortSignal;
+    /** 禁用全部工具(纯文本推理,判分等廉价场景用)。 */
+    noTools?: boolean;
+    /** 子 agent 的工作目录(git worktree 隔离等场景);缺省继承主进程 cwd。 */
+    cwd?: string;
+}
+/** 单个子 agent 的 token/费用用量(汇总自会话内全部 assistant 消息)。 */
+export interface SubagentUsage {
+    totalTokens: number;
+    costUsd: number;
 }
 export interface SubagentOutcome {
     ok: boolean;
     text: string;
+    usage: SubagentUsage;
 }
 /**
  * Spawn 一个独立上下文的子 agent 执行任务,返回其最终文本输出。

package/dist/subagent.js

@@ -1,4 +1,4 @@
-import { createAgentSession, ModelRuntime, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, DefaultResourceLoader, getAgentDir, ModelRuntime, SessionManager, } from "@earendil-works/pi-coding-agent";
 // ---- 子 agent spawn 基础设施:spawn_subagent 工具与 workflow runner 共用 ----
 /** 同时在跑的子 agent 上限;超额排队,防止打爆网关。 */
 export const SUBAGENT_CONCURRENCY = 4;
@@ -22,6 +22,36 @@ function extractFinalText(messages) {
     }
     return "(子 agent 结束但没有文本输出)";
 }
+/**
+ * 汇总会话内全部 assistant 消息的 token 与费用。
+ * pi-ai 对自定义 provider(models.json)不算钱(usage.cost.total 恒 0),
+ * 所以优先用自带费用,否则按模型价率(美元/百万 token)自算。
+ */
+function extractUsage(messages, model) {
+    let totalTokens = 0;
+    let costUsd = 0;
+    const rates = model?.cost;
+    for (const m of messages) {
+        const msg = m;
+        const usage = msg?.usage;
+        if (!usage || msg.role !== "assistant")
+            continue;
+        totalTokens += usage.totalTokens ?? 0;
+        const reported = usage.cost?.total ?? 0;
+        if (reported > 0) {
+            costUsd += reported;
+        }
+        else if (rates) {
+            costUsd +=
+                ((usage.input ?? 0) * rates.input +
+                    (usage.output ?? 0) * rates.output +
+                    (usage.cacheRead ?? 0) * rates.cacheRead +
+                    (usage.cacheWrite ?? 0) * rates.cacheWrite) /
+                    1_000_000;
+        }
+    }
+    return { totalTokens, costUsd };
+}
 /**
  * Spawn 一个独立上下文的子 agent 执行任务,返回其最终文本输出。
  * 模型解析:"provider/id" 精确匹配;裸 id(如 deepseek-v4-flash)先按原样找,
@@ -48,10 +78,25 @@ export async function runSubagent(opts) {
     else {
         model = undefined;
     }
+    // 子会话不加载精简 UI 扩展:它用 process.cwd() 重建内置工具,会破坏自定义
+    // cwd(worktree 隔离)下的路径解析;且 UI 美化对无界面的子 agent 毫无意义
+    const loader = new DefaultResourceLoader({
+        agentDir: getAgentDir(),
+        cwd: opts.cwd ?? process.cwd(),
+        extensionsOverride: (base) => ({
+            ...base,
+            extensions: base.extensions.filter((e) => !JSON.stringify(e).includes("u1s1-compact-ui")),
+        }),
+    });
+    await loader.reload();
     const { session } = await createAgentSession({
-        sessionManager: SessionManager.inMemory(process.cwd()),
+        // cwd 必须同时传给顶层(工具的路径解析基于它)和 sessionManager
+        ...(opts.cwd ? { cwd: opts.cwd } : {}),
+        resourceLoader: loader,
+        sessionManager: SessionManager.inMemory(opts.cwd ?? process.cwd()),
         modelRuntime: sharedModelRuntime,
         ...(model ? { model } : {}),
+        ...(opts.noTools ? { noTools: "all" } : {}),
     });
     const timeoutMs = opts.timeoutMs ?? SUBAGENT_TIMEOUT_MS;
     const timer = setTimeout(() => void session.abort(), timeoutMs);
@@ -67,7 +112,8 @@ export async function runSubagent(opts) {
     }
     if (opts.signal?.aborted)
         throw new Error("已取消");
-    return { ok: true, text: extractFinalText(session.messages) };
+    const messages = session.messages;
+    return { ok: true, text: extractFinalText(messages), usage: extractUsage(messages, model) };
 }
 /**
  * 固定并发的工作池:limit 个工人依次领任务跑完一个补位一个。

package/dist/tools.js

@@ -213,7 +213,7 @@ export function createSubagentTool(getParentModel) {
             const outcomes = new Array(list.length);
             try {
                 await runPool(list, SUBAGENT_CONCURRENCY, async (task, i) => {
-                    outcomes[i] = await runSubagent({ task, parentModel, model: params.model, timeoutMs, signal }).catch((e) => ({ ok: false, text: e.message }));
+                    outcomes[i] = await runSubagent({ task, parentModel, model: params.model, timeoutMs, signal }).catch((e) => ({ ok: false, text: e.message, usage: { totalTokens: 0, costUsd: 0 } }));
                 }, signal);
             }
             finally {

package/dist/web.js

@@ -2,7 +2,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { mkdirSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
-import { cleanupBrandThemes, endpointKeyEnv, ensureAuthCredential, ensureBrandPrompt, ensureDefaultSettings, ensureProviderModels, scrubForeignProviderEnv, writeWebToolsExtension, } from "./agent-setup.js";
+import { cleanupBrandThemes, endpointKeyEnv, ensureAuthCredential, ensureBrandPrompt, ensureWorkflowPromptTemplate, ensureDefaultSettings, ensureProviderModels, scrubForeignProviderEnv, writeWebToolsExtension, } from "./agent-setup.js";
 import { agentDir, apiModelToDef, resolvePreferredModel, setModelsFromApi, u1s1Dir, writeAgentDefaultModel, } from "./config.js";
 import { ensureSearchTools } from "./search-tools.js";
 import { ensureUsableShell } from "./shell-doctor.js";
@@ -47,6 +47,8 @@ export async function prepareWebEnv(cfg) {
     }
     await endpointsReady;
     ensureBrandPrompt(await shellReady);
+    // /workflow 提示词模板与 TUI 同源,web/桌面版也要有
+    ensureWorkflowPromptTemplate();
     ensureProviderModels(cfg);
     // pi-web-ui 靠 auth.json 判断「已配置」,否则网页会弹 pi 安装引导
     ensureAuthCredential();

package/dist/workflow/runner.d.ts

@@ -1,6 +1,8 @@
 import { type ParentModelRef } from "../subagent.js";
 /** 整个 run 的默认墙钟上限。 */
 export declare const WORKFLOW_TIMEOUT_MS: number;
+/** 默认整个 run 的 token 预算;0 或负数表示不设限。 */
+export declare const WORKFLOW_DEFAULT_BUDGET_TOKENS = 20000000;
 /** 静态白名单校验:语法能编译 + 不碰沙箱之外的任何能力。 */
 export declare function validateScript(code: string): string[];
 export interface WorkflowRunResult {
@@ -15,6 +17,15 @@ export interface WorkflowRunResult {
         aborted: boolean;
     };
 }
+export interface WorkflowProgress {
+    spawns: number;
+    ok: number;
+    failed: number;
+    cached: number;
+    running: number;
+    spentTokens: number;
+    budgetTokens: number;
+}
 export interface WorkflowRunOptions {
     /** 脚本源码(调用方负责落盘)。 */
     code: string;
@@ -24,6 +35,10 @@ export interface WorkflowRunOptions {
     parentModel: ParentModelRef;
     signal?: AbortSignal;
     timeoutMs?: number;
+    /** 整个 run 的 token 上限;缺省 WORKFLOW_DEFAULT_BUDGET_TOKENS,<=0 不限。 */
+    budgetTokens?: number;
+    /** 每次子任务状态变化时回调(工具层节流后转成流式进度)。 */
+    onProgress?: (p: WorkflowProgress) => void;
 }
 /** 执行一个 workflow 脚本,返回给主对话的报告。不抛错——失败也进报告让模型自行修复。 */
 export declare function runWorkflow(opts: WorkflowRunOptions): Promise<WorkflowRunResult>;

package/dist/workflow/runner.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import vm from "node:vm";
 import { dirname, resolve } from "node:path";
 import { runPool, runSubagent, SUBAGENT_CONCURRENCY } from "../subagent.js";
@@ -11,6 +12,8 @@ export const WORKFLOW_TIMEOUT_MS = 30 * 60_000;
 const PER_TASK_TIMEOUT_MS = 15 * 60_000;
 /** 报告里最多保留多少行脚本 log 输出。 */
 const MAX_LOG_LINES = 60;
+/** 默认整个 run 的 token 预算;0 或负数表示不设限。 */
+export const WORKFLOW_DEFAULT_BUDGET_TOKENS = 20_000_000;
 /** JSONL 进度存档:一行一个已完成的子任务,断点续跑时按 key 跳过。 */
 class ProgressStore {
     path;
@@ -108,7 +111,36 @@ export async function runWorkflow(opts) {
         internal.abort(new Error(`整个工作流超时(${Math.round((opts.timeoutMs ?? WORKFLOW_TIMEOUT_MS) / 60_000)} 分钟)`));
     }, opts.timeoutMs ?? WORKFLOW_TIMEOUT_MS);
     const store = new ProgressStore(opts.progressPath);
-    /** 注入沙箱的 subagent():字符串或 {task, model} 都行,返回最终输出文本。 */
+    const budgetTokens = opts.budgetTokens ?? WORKFLOW_DEFAULT_BUDGET_TOKENS;
+    let spentTokens = 0;
+    let running = 0;
+    const progress = { spawns: 0, ok: 0, failed: 0, cached: 0, running: 0, spentTokens: 0, budgetTokens };
+    const reportProgress = () => {
+        progress.spentTokens = spentTokens;
+        opts.onProgress?.({ ...progress });
+    };
+    /** git worktree 隔离:在 .u1s1/worktrees/ 下建临时工作树,返回其路径。 */
+    let worktreeSeq = 0;
+    function createTempWorktree() {
+        const dir = resolve(workflowsDir(), "../../.u1s1-worktrees", `wf-${Date.now()}-${++worktreeSeq}`);
+        execFileSync("git", ["worktree", "add", "--detach", dir], { stdio: "pipe" });
+        return dir;
+    }
+    function removeWorktree(dir) {
+        try {
+            execFileSync("git", ["worktree", "remove", "--force", dir], { stdio: "pipe" });
+        }
+        catch {
+            rmSync(dir, { recursive: true, force: true });
+            try {
+                execFileSync("git", ["worktree", "prune"], { stdio: "pipe" });
+            }
+            catch {
+                // 尽力清理即可
+            }
+        }
+    }
+    /** 注入沙箱的 subagent():字符串或 {task, model, worktree} 都行,返回最终输出文本。 */
     async function subagentImpl(input) {
         const o = typeof input === "string" ? { task: input } : (input ?? {});
         const task = typeof o.task === "string" ? o.task.trim() : "";
@@ -117,18 +149,30 @@ export async function runWorkflow(opts) {
         const model = typeof o.model === "string" && o.model ? o.model : undefined;
         if (internal.signal.aborted)
             throw new Error("工作流已中止,不再派发新子任务");
+        if (budgetTokens > 0 && spentTokens >= budgetTokens) {
+            throw new Error(`token 预算已用尽(已用 ${spentTokens.toLocaleString()} / 上限 ${budgetTokens.toLocaleString()}),不再派发新子任务`);
+        }
         const key = taskKey(task, model);
         if (opts.resume) {
             const prev = store.get(key);
             if (prev) {
                 stats.cached++;
+                progress.cached = stats.cached;
+                reportProgress();
                 if (prev.ok)
                     return prev.text;
                 throw new Error(prev.text);
             }
         }
         stats.spawns++;
+        progress.spawns = stats.spawns;
+        running++;
+        progress.running = running;
+        reportProgress();
         const t0 = Date.now();
+        let worktreeDir;
+        if (o.worktree === true)
+            worktreeDir = createTempWorktree();
         try {
             const out = await runSubagent({
                 task,
@@ -136,17 +180,42 @@ export async function runWorkflow(opts) {
                 parentModel: opts.parentModel,
                 timeoutMs: PER_TASK_TIMEOUT_MS,
                 signal: internal.signal,
+                cwd: worktreeDir,
+                noTools: o.noTools === true,
             });
             stats.ok++;
+            progress.ok = stats.ok;
+            spentTokens += out.usage.totalTokens;
             store.append({ key, task: task.slice(0, 120), ok: true, text: out.text, ms: Date.now() - t0 });
             return out.text;
         }
         catch (e) {
             stats.failed++;
+            progress.failed = stats.failed;
             const msg = e.message || "未知错误";
             store.append({ key, task: task.slice(0, 120), ok: false, text: msg, ms: Date.now() - t0 });
             throw new Error(msg);
         }
+        finally {
+            if (worktreeDir)
+                removeWorktree(worktreeDir);
+            running--;
+            progress.running = running;
+            reportProgress();
+        }
+    }
+    /** 注入沙箱的 judge():廉价无工具模型调用,严格回答 PASS/FAIL,转成布尔。 */
+    async function judgeImpl(question) {
+        if (typeof question !== "string" || !question.trim())
+            throw new Error("judge() 需要问题字符串");
+        const answer = await subagentImpl({
+            task: `回答以下判定问题。只允许回答一个词:PASS 或 FAIL,不要任何其他内容。\n\n判定问题:${question.trim()}`,
+            noTools: true,
+        });
+        const pass = /\bPASS\b/i.test(answer) && !/\bFAIL\b/i.test(answer);
+        if (!pass && !/\bFAIL\b/i.test(answer))
+            logs.push(`⚠ judge 回答无法解析,按 FAIL 处理:${answer.slice(0, 120)}`);
+        return pass;
     }
     /** barrier 扇出:全部并发(封顶排队),单个失败该项为 null,不拖垮整批。 */
     async function parallel(thunks) {
@@ -201,6 +270,7 @@ export async function runWorkflow(opts) {
         subagent: subagentImpl,
         parallel,
         pipeline,
+        judge: judgeImpl,
         log: pushLog,
         console: { log: pushLog, info: pushLog, warn: pushLog, error: pushLog },
         setTimeout: (fn, ms) => setTimeout(fn, Math.max(0, Math.min(Number(ms) || 0, 120_000))),
@@ -223,8 +293,9 @@ export async function runWorkflow(opts) {
     }
     const seconds = Math.round((Date.now() - started) / 1000);
     const aborted = internal.signal.aborted;
-    const details = { ...stats, seconds, aborted };
-    const lines = [`工作流结束,用时 ${seconds}s · 子任务 ✓${stats.ok} ✗${stats.failed}${stats.cached ? ` · 续跑命中 ${stats.cached}` : ""}${timedOut ? " · ⏱ 整体超时" : ""}${aborted && !timedOut ? " · 已中止" : ""}`, ""];
+    const budgetExhausted = budgetTokens > 0 && spentTokens >= budgetTokens;
+    const details = { ...stats, seconds, aborted, spentTokens, budgetExhausted };
+    const lines = [`工作流结束,用时 ${seconds}s · 子任务 ✓${stats.ok} ✗${stats.failed}${stats.cached ? ` · 续跑命中 ${stats.cached}` : ""} · 用 ${spentTokens.toLocaleString()} tokens${budgetTokens > 0 ? ` / 预算 ${budgetTokens.toLocaleString()}` : " (不限)"}${timedOut ? " · ⏱ 整体超时" : ""}${aborted && !timedOut ? " · 已中止" : ""}`, ""];
     if (completionValue !== undefined) {
         let shown;
         try {

package/dist/workflow/templates.d.ts

@@ -0,0 +1,11 @@
+export interface WorkflowTemplate {
+    name: string;
+    description: string;
+    /** 生成脚本源码;input 已由调用方做过形状校验。 */
+    build: (input: Record<string, unknown>) => string;
+    /** 给模型看的 input 说明。 */
+    inputHint: string;
+}
+export declare const TEMPLATES: Record<string, WorkflowTemplate>;
+/** 按模板名生成脚本;生成后自检必须过静态校验(防模板本身写出不合规代码)。 */
+export declare function buildFromTemplate(template: string, input: Record<string, unknown>): string;

package/dist/workflow/templates.js

@@ -0,0 +1,167 @@
+import { execFileSync } from "node:child_process";
+import { validateScript } from "./runner.js";
+function str(v, fallback = "") {
+    return typeof v === "string" && v.trim() ? v.trim() : fallback;
+}
+function strArray(v) {
+    return Array.isArray(v)
+        ? v.filter((x) => typeof x === "string" && !!x.trim()).map((x) => x.trim())
+        : [];
+}
+/** JSON.stringify 后内插进脚本;保证引号安全。 */
+function lit(v) {
+    return JSON.stringify(v ?? null);
+}
+/** git 改动文件列表(模板构建期在主进程执行,不进沙箱)。 */
+function gitDiffFiles() {
+    try {
+        const out = execFileSync("git", ["diff", "--name-only", "HEAD"], { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+        return out.split("\n").map((s) => s.trim()).filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+export const TEMPLATES = {
+    i18n: {
+        name: "i18n",
+        description: "批量多语言翻译:每个语言一个子 agent 并行翻译,完成后统一校验 key 对齐并自动修复",
+        inputHint: '{ "langs": ["en", "ja", "de"], "source": "src/locales/zh.json", "dir": "src/locales" } — source/dir 可省略(默认 src/locales/zh.json 与同目录)',
+        build(input) {
+            const langs = strArray(input.langs);
+            if (langs.length === 0)
+                throw new Error('i18n 模板需要 langs 数组,例如 { "langs": ["en", "ja"] }');
+            const source = str(input.source, "src/locales/zh.json");
+            const dir = str(input.dir, source.includes("/") ? source.slice(0, source.lastIndexOf("/")) : "src/locales");
+            return `
+const langs = ${lit(langs)};
+log("i18n:翻译 " + langs.length + " 个语言,源文件 ${source}");
+const results = await parallel(langs.map(lang => () =>
+  subagent({
+    task: "读取 ${source},把所有文案翻译成对应语言(保持所有 key 不变、输出合法 JSON、译文自然地道)," +
+      "写入 ${dir}/" + lang + ".json。写完后重新读一遍文件,确认是合法 JSON 且 key 与源文件完全一致。" +
+      "目标语言代码:" + lang
+  })
+));
+const okLangs = langs.filter((_, i) => results[i] !== null);
+if (okLangs.length > 0) {
+  await subagent({
+    task: "对照 ${source} 检查 ${dir}/ 目录下这些语言的翻译文件:" + okLangs.join(",") + "." +
+      "逐个核对 key 是否与源文件完全一致、JSON 是否合法、译文是否有明显机翻痕迹,发现问题直接修复。最后汇报每个语言的状态"
+  });
+}
+return { translated: okLangs, failed: langs.filter(l => !okLangs.includes(l)) };
+`;
+        },
+    },
+    review: {
+        name: "review",
+        description: "全面代码审查:每个文件一个评审 agent 并行审查,发现项再交独立 agent 对抗性验证,只保留核实为真的问题",
+        inputHint: '{ "files": ["src/a.ts", "src/b.ts"] } — files 可省略,默认取 git diff --name-only HEAD 的改动文件',
+        build(input) {
+            let files = strArray(input.files);
+            if (files.length === 0)
+                files = gitDiffFiles();
+            if (files.length === 0)
+                throw new Error("review 模板需要 files 数组,或当前仓库有未提交改动");
+            return `
+const files = ${lit(files)};
+log("review:评审 " + files.length + " 个文件,发现项将做对抗性验证");
+const reports = await parallel(files.map(f => () =>
+  subagent({
+    task: "通读 " + f + " 及其直接依赖,做代码审查:正确性 bug、安全漏洞、明显的性能问题。" +
+      "只报告有把握的问题,每条给出文件、行号、严重程度(高/中/低)、问题描述和建议修法。没有问题就明确说无发现。"
+  })
+));
+const findings = reports.filter(Boolean).join("\\n\\n---\\n\\n");
+if (!findings.trim()) return { verified: "(所有文件均无发现)" };
+const verified = await subagent({
+  task: "下面是一份代码审查发现列表。逐条对抗性验证:打开涉及的文件核对,剔除不成立、夸大或已过时的条目," +
+    "只保留核实为真的问题,按严重程度排序输出完整清单。\\n\\n" + findings
+});
+return { verified };
+`;
+        },
+    },
+    research: {
+        name: "research",
+        description: "并行研究:每个方向一个子 agent 独立调查(可联网),最后汇总成一份综合报告",
+        inputHint: '{ "questions": ["方向一", "方向二"], "context": "可选背景" }',
+        build(input) {
+            const questions = strArray(input.questions);
+            if (questions.length === 0)
+                throw new Error('research 模板需要 questions 数组,例如 { "questions": ["竞品A的定价", "竞品B的功能"] }');
+            const context = str(input.context);
+            const contextLine = context ? `调查背景:${context}。` : "";
+            return `
+const questions = ${lit(questions)};
+log("research:并行调查 " + questions.length + " 个方向");
+const reports = await parallel(questions.map(q => () =>
+  subagent({
+    task: "调查以下问题,可以用 web_search/web_fetch 联网,也可以读本地代码和文档。" +
+      "输出:关键事实(带来源)、不同观点、你的结论。${contextLine}问题:" + q
+  })
+));
+const merged = reports
+  .map((r, i) => (r ? "## 方向 " + (i + 1) + ":" + questions[i] + "\\n\\n" + r : null))
+  .filter(Boolean)
+  .join("\\n\\n");
+if (!merged.trim()) return { synthesis: "(所有方向都失败了)", failed: questions.length };
+const synthesis = await subagent({
+  task: "把以下几份调查报告综合成一份结论性报告:先给核心结论(不超过 5 条),再给分方向要点," +
+    "最后列分歧点和待确认项。不要编造报告里没有的信息。\\n\\n" + merged
+});
+return { synthesis };
+`;
+        },
+    },
+    refactor: {
+        name: "refactor",
+        description: "批量重构/迁移:先由一个 agent 读代表文件制定统一规则,然后每个文件一个子 agent 在独立 worktree 里套用规则,互不冲突",
+        inputHint: '{ "instruction": "把所有 var 改为 const", "files": ["src/a.ts", ...] } — files 省略时用 git diff 改动文件',
+        build(input) {
+            const instruction = str(input.instruction);
+            if (!instruction)
+                throw new Error('refactor 模板需要 instruction,例如 { "instruction": "把 var 全部改为 const" }');
+            const files = strArray(input.files);
+            return `
+const instruction = ${lit(instruction)};
+let targetFiles = ${lit(files)};
+if (targetFiles.length === 0) {
+  const listed = await subagent({
+    task: "运行 git diff --name-only HEAD,把输出的文件路径一行一个原样返回,不要加任何其他文字。"
+  });
+  targetFiles = listed.split("\\n").map(s => s.trim()).filter(Boolean);
+}
+if (targetFiles.length === 0) throw new Error("没有可处理的文件:files 为空且 git 无改动");
+log("refactor:共 " + targetFiles.length + " 个文件,先制定统一规则");
+const rule = await subagent({
+  task: "我们要对一批文件做统一重构:" + instruction + "。" +
+    "先读其中 1-2 个代表性文件了解现状,然后输出一份精确的重构规则清单(每条:什么模式改成什么、边界情况怎么处理)。" +
+    "规则要具体到可以直接照做,不要空话。涉及文件:" + targetFiles.slice(0, 10).join(",")
+});
+const results = await parallel(targetFiles.map(f => () =>
+  subagent({
+    task: "按以下重构规则处理文件 " + f + ",改完检查该文件语法正确(必要时运行 tsc 或构建验证)。\\n\\n重构规则:\\n" + rule,
+    worktree: true
+  })
+));
+const done = targetFiles.filter((_, i) => results[i] !== null);
+return { applied: done, failed: targetFiles.filter(f => !done.includes(f)), rule };
+`;
+        },
+    },
+};
+/** 按模板名生成脚本;生成后自检必须过静态校验(防模板本身写出不合规代码)。 */
+export function buildFromTemplate(template, input) {
+    const t = TEMPLATES[template];
+    if (!t) {
+        throw new Error(`未知模板 "${template}",可用:${Object.keys(TEMPLATES).join(", ")}`);
+    }
+    const code = t.build(input ?? {});
+    const errors = validateScript(code);
+    if (errors.length > 0) {
+        throw new Error(`模板 ${template} 生成的脚本未通过静态校验(模板 bug,请反馈):${errors.join(";")}`);
+    }
+    return code;
+}

package/dist/workflow/tool.d.ts

@@ -6,7 +6,11 @@ import type { ParentModelRef } from "../subagent.js";
  */
 export declare function createRunWorkflowTool(getParentModel: () => ParentModelRef): import("@earendil-works/pi-coding-agent").ToolDefinition<Type.TObject<{
     script: Type.TOptional<Type.TString>;
+    template: Type.TOptional<Type.TString>;
+    input: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
     script_path: Type.TOptional<Type.TString>;
+    save_as: Type.TOptional<Type.TString>;
     resume: Type.TOptional<Type.TBoolean>;
     timeout_minutes: Type.TOptional<Type.TNumber>;
+    budget_tokens: Type.TOptional<Type.TNumber>;
 }>, unknown, any> & import("@earendil-works/pi-coding-agent").ToolDefinition<any, any, any>;

package/dist/workflow/tool.js

@@ -1,10 +1,11 @@
-import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { compactResultRender, truncate } from "../tools.js";
-import { runWorkflow, saveWorkflowScript, validateScript, workflowsDir, WORKFLOW_TIMEOUT_MS, } from "./runner.js";
+import { runWorkflow, saveWorkflowScript, validateScript, workflowsDir, WORKFLOW_DEFAULT_BUDGET_TOKENS, WORKFLOW_TIMEOUT_MS, } from "./runner.js";
+import { buildFromTemplate, TEMPLATES } from "./templates.js";
 /**
  * run_workflow 工具:主 agent 把模型生成的编排脚本交给 WorkflowRunner 执行。
  * 脚本在 vm 沙箱里跑,只能用注入的 subagent/parallel/pipeline 原语。
@@ -27,9 +28,20 @@ export function createRunWorkflowTool(getParentModel) {
         ],
         parameters: Type.Object({
             script: Type.Optional(Type.String({ description: "Full JavaScript source of the orchestration script (top-level await allowed)." })),
+            template: Type.Optional(Type.String({
+                description: `Use a built-in template instead of writing a script: ${Object.keys(TEMPLATES).join(" / ")}. ` +
+                    "Provide `input` to parametrize it. Prefer this over hand-writing a script when a template fits.",
+            })),
+            input: Type.Optional(Type.Record(Type.String(), Type.Unknown(), {
+                description: 'Parameters for `template`, e.g. i18n: { "langs": ["en", "ja"] }; review/refactor: { "files": [...] } or omit for git-diff files; research: { "questions": [...] }.',
+            })),
             script_path: Type.Optional(Type.String({
                 description: "Path to an existing workflow script under .u1s1/workflows/ — rerun it instead of passing `script`.",
             })),
+            save_as: Type.Optional(Type.String({
+                description: 'Save this run\'s script as .u1s1/workflows/<name>.mjs (letters/digits/-/_) for easy reuse; rerun later via script_path. Fails if the name already exists.',
+                pattern: "^[a-zA-Z0-9_-]+$",
+            })),
             resume: Type.Optional(Type.Boolean({
                 description: "Skip sub-tasks already recorded as succeeded in the progress file (for crash/interrupt recovery).",
             })),
@@ -38,6 +50,11 @@ export function createRunWorkflowTool(getParentModel) {
                 minimum: 1,
                 maximum: 180,
             })),
+            budget_tokens: Type.Optional(Type.Number({
+                description: `Total token ceiling for the whole run across all sub-agents (default ${WORKFLOW_DEFAULT_BUDGET_TOKENS}). Once exceeded, no new sub-agents are spawned; running ones finish. Use 0 for unlimited.`,
+                minimum: 0,
+                maximum: 1_000_000_000,
+            })),
         }),
         // 精简展示与 spawn_subagent 同款:收起一行摘要,ctrl+o 展开报告
         renderShell: "self",
@@ -53,15 +70,27 @@ export function createRunWorkflowTool(getParentModel) {
                 : "🧭 工作流";
             return compactResultRender(result, options, theme, context, summary);
         },
-        async execute(_toolCallId, params, signal) {
+        async execute(_toolCallId, params, signal, onUpdate) {
             let code = params.script?.trim();
             let scriptPath;
+            const named = params.save_as?.trim();
+            if (named && !/^[a-zA-Z0-9_-]+$/.test(named)) {
+                throw new Error("save_as 只允许字母、数字、横线和下划线");
+            }
             if (code) {
                 const errors = validateScript(code);
                 if (errors.length > 0) {
                     throw new Error(`脚本未通过静态校验,请修复后重试:\n- ${errors.join("\n- ")}`);
                 }
-                scriptPath = saveWorkflowScript(code);
+            }
+            else if (params.template?.trim()) {
+                // 内置模板:模型只填参数,脚本由模板生成(生成后自检过静态校验)
+                try {
+                    code = buildFromTemplate(params.template.trim(), (params.input ?? {}));
+                }
+                catch (e) {
+                    throw new Error(`${e.message}\n模板 input 说明:${TEMPLATES[params.template.trim()]?.inputHint ?? "—"}`);
+                }
             }
             else if (params.script_path?.trim()) {
                 scriptPath = resolve(params.script_path.trim());
@@ -73,9 +102,38 @@ export function createRunWorkflowTool(getParentModel) {
                 }
             }
             else {
-                throw new Error("script 和 script_path 至少填一个");
+                throw new Error("script、template、script_path 至少填一个");
+            }
+            // 落盘:save_as 用语义化名字(同名报错防覆盖进度配对),否则时间戳名;
+            // script_path 分支上面已读入,不重复落盘
+            if (!scriptPath) {
+                scriptPath = named ? resolve(workflowsDir(), `${named}.mjs`) : saveWorkflowScript(code ?? "");
+                if (named && existsSync(scriptPath)) {
+                    throw new Error(`工作流 "${named}" 已存在(${scriptPath})。要重跑它请用 script_path 指向该文件(可加 resume:true 续跑);要新建请换个名字`);
+                }
+                mkdirSync(dirname(scriptPath), { recursive: true });
+                writeFileSync(scriptPath, code ?? "");
             }
             const progressPath = scriptPath.replace(/\.mjs$/, ".progress.jsonl");
+            // 流式进度:onProgress 高频触发,节流到 ≥2s 一次才推给 TUI
+            let lastPush = 0;
+            const onProgress = onUpdate
+                ? (p) => {
+                    const now = Date.now();
+                    if (now - lastPush < 2_000)
+                        return;
+                    lastPush = now;
+                    onUpdate({
+                        content: [
+                            {
+                                type: "text",
+                                text: `🧭 子任务 ✓${p.ok} ✗${p.failed}${p.cached ? ` 缓存${p.cached}` : ""} · 在跑 ${p.running} · ${(p.spentTokens / 1000).toFixed(0)}k${p.budgetTokens > 0 ? ` / ${(p.budgetTokens / 1000).toFixed(0)}k tokens` : ""}`,
+                            },
+                        ],
+                        details: p,
+                    });
+                }
+                : undefined;
             const result = await runWorkflow({
                 code: code ?? "",
                 progressPath,
@@ -83,6 +141,8 @@ export function createRunWorkflowTool(getParentModel) {
                 parentModel: getParentModel(),
                 signal,
                 timeoutMs: Math.min(180, params.timeout_minutes ?? WORKFLOW_TIMEOUT_MS / 60_000) * 60_000,
+                budgetTokens: params.budget_tokens,
+                onProgress,
             });
             return {
                 content: [{ type: "text", text: truncate(result.report) }],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u1s1-cli",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "u1s1 — 有一说一,最省心的 AI 编程搭子。终端里用中文说需求,AI 帮你读文件、改代码、跑命令。",
   "type": "module",
   "bin": {