@bolloon/bolloon-agent 0.4.33 → 0.5.1

package/dist/agents/goal-state-reducer.js

@@ -0,0 +1,406 @@
+/**
+ * goal-state-reducer.ts — **改动 Goal 状态的唯一漏斗** (M0 接线冻结, 2026-09-25)
+ *
+ * ## 为什么必须只有这一个漏斗
+ *
+ * 接线前, 全仓有 6 个模块各拿 `updateGoal(goalId, { status: ... })` 直接改 Goal 状态
+ * (Supervisor / 技能门禁 / 外部事件 / 联系方式链 / 判据提议 / Web 唤醒)。同一个 Goal 的终态
+ * 于是有两个以上的写入者 —— 谁最后写谁赢, 且没有任何一处能看到"这个状态是怎么来的"。
+ *
+ * 这个模块把**所有** Goal 状态变更收敛成一个两步:
+ *
+ *   ① `planGoalStateChange(intent)` —— **纯函数**: 吃一个声明式的**意图** (intent), 吐出计划
+ *      (`status` / `continuation` 补丁 / 证据 / 未解决项 / 结构化原因)。不碰盘、不读钟、不 import fs。
+ *      纯函数的意义: 状态判决可以被单测穷举, 也可以被门断言, 而不必先造一个真 Goal。
+ *   ② `applyGoalStatePlan(plan)` —— **唯一**的落盘出口 (调 goal-store 的 `updateGoal` / `setContinuation`
+ *      / `addEvidence`)。源码级门钉住: 除 `goal-store.ts` 本体外, 只有本文件允许出现
+ *      `updateGoal(..., { status: ... })` (见 `wiring/seams.ts` 的规则 ②)。
+ *
+ * ## 边界 (刻意不做)
+ *
+ * - **不新增状态机**: intent 的名字就是既有的调用点语义, 一个不多。
+ * - **不新增存储**: 全部落进既有的 Goal / continuation 字段。
+ * - **不决定"是否继续"**: 那是 Supervisor + continuation 接缝的事 (规则 ①)。本模块只负责
+ *   "把已经作出的决定**如实**写成 Goal 的状态", 并对完成门**不放松** (completed 仍必须过
+ *   `completeGoalIfEligible`; 门拒绝就退回 active, 不许装作完成)。
+ * - **不碰 Run**: 关闭 Run 只有 closeRun 一条路 (规则 ③), 与本模块无关。
+ */
+import { addEvidence, completeGoalIfEligible, readGoal, setContinuation, setUnresolved, updateGoal, } from './goal-store.js';
+// ============================================================================
+// §1. 意图 (intent) —— 声明式, 一个意图 = 一个既有调用点的语义
+// ============================================================================
+export const GOAL_STATE_INTENTS = [
+    'closure_outcome', // Run 收尾后的合并结论 (Supervisor / Runner 独立收尾)
+    'flywheel_stop', // 飞轮明确判停 (fail / pause / 无进展熔断 / 硬底线)
+    'user_revoked_goal', // 用户明确撤销 → abandoned (规则 1: 用户撤销优先级最高)
+    'skill_gate_block', // 技能门禁拦下 → 交人 (不启动 Run)
+    'skill_gate_record', // 只记技能就绪事实, 不改状态
+    'skill_upgrade_approved', // 人工批准技能升级 → 回到可继续
+    'external_wait_enter', // 进入"等外部回话"
+    'external_wait_expired', // 外部等待超时 → 交人
+    'external_event_arrived', // 外部事件到达 → 拉回 active
+    'contact_revoked_human', // 联系方式授权被撤销 → 交人
+    'criteria_needs_human', // 判据提不出来 → 交人
+    'block_escalated_human', // 子 Agent 被阻塞且已升级 → 交人 (规则 ④ 的一条终止路径)
+    'manual_wake', // 人明确说"外部条件我已满足"
+    'scheduled_wake', // 到点唤醒 (retry_wait 的 wakeAt 到了) → 回到可继续 (2026-09-25 M5 真跑)
+];
+function planBase(goalId, intent, reason) {
+    return {
+        goalId,
+        intent,
+        status: null,
+        evidence: [],
+        unresolvedItems: null,
+        completionGate: false,
+        reason,
+    };
+}
+/**
+ * 意图 → 计划。**纯函数**: 不读盘、不读钟 (`now`/`reason` 全部由调用方注入)。
+ *
+ * 阴性对照 (门里真跑): 把 `closure_outcome` 的 `completionGate` 从 true 改成 false →
+ * 完成门就被绕过了, `goal-state-reducer.test.ts` 的"完成门拒绝 → 退回 active"立刻判红。
+ */
+export function planGoalStateChange(input) {
+    const { goalId, now } = input;
+    const by = input.by ?? 'system';
+    const runRef = input.runId ? `run=${input.runId}` : 'run=-';
+    switch (input.intent) {
+        case 'closure_outcome': {
+            const o = input.outcome;
+            if (!o) {
+                // 没有结论就不许改状态 (不许"顺手"写一个)
+                return planBase(goalId, input.intent, '缺 outcome: 收尾结论未给出 → 不改 Goal 状态');
+            }
+            const p = planBase(goalId, input.intent, o.reason);
+            p.status = o.goalStatus;
+            p.completionGate = o.goalStatus === 'completed';
+            p.continuation = o.continuation;
+            if (o.goalStatus === 'failed' || o.goalStatus === 'abandoned') {
+                p.resolution = { reason: o.reason, at: now };
+            }
+            if (input.runEvidence?.length) {
+                p.evidence = input.runEvidence.slice(-5).map((s) => `${runRef}: ${String(s).slice(0, 200)}`);
+            }
+            return p;
+        }
+        case 'flywheel_stop': {
+            const status = input.stopStatus ?? 'needs_human';
+            const p = planBase(goalId, input.intent, `飞轮判停 (${status}): ${input.reason ?? ''}`.trim());
+            p.status = status;
+            if (status === 'failed')
+                p.resolution = { reason: `飞轮判不可达: ${input.reason ?? ''}`, at: now };
+            p.continuation = {
+                state: status,
+                autoContinue: false,
+                wakeAt: undefined,
+                wakeReason: status === 'failed' ? 'failed' : status === 'paused' ? 'paused' : 'needs_human',
+                lastDecisionId: input.decisionId ?? undefined,
+                unresolvedItems: [...(input.unresolvedItems ?? [])],
+                nextAction: input.nextAction || undefined,
+                updatedAt: now,
+            };
+            p.unresolvedItems = [...(input.unresolvedItems ?? [])].slice(0, 30);
+            return p;
+        }
+        case 'user_revoked_goal': {
+            const reason = input.reason || '用户明确撤销 → 目标终止 (不许继续跑)';
+            const p = planBase(goalId, input.intent, reason);
+            p.status = 'abandoned';
+            p.resolution = { reason, at: now };
+            p.continuation = {
+                autoContinue: false,
+                wakeAt: undefined,
+                wakeReason: 'active',
+                state: 'abandoned',
+                updatedAt: now,
+            };
+            p.evidence = [`用户撤销 (by ${by}): ${reason}`];
+            return p;
+        }
+        case 'skill_gate_block': {
+            const reason = input.reason || '技能未就绪';
+            const p = planBase(goalId, input.intent, `技能门禁拦截: ${reason}`);
+            p.status = 'needs_human';
+            p.continuation = {
+                wakeReason: 'needs_human',
+                autoContinue: false,
+                needsExternal: undefined,
+                skillReadiness: input.skillReadiness ?? { ok: false, at: now, reason },
+                updatedAt: now,
+            };
+            p.clearContinuationFields = ['needsExternal'];
+            p.evidence = [`技能门禁拦截 (by ${by}): ${reason}`];
+            return p;
+        }
+        case 'skill_gate_record': {
+            const p = planBase(goalId, input.intent, '技能就绪检查结论已记事实 (不改状态)');
+            p.continuation = { skillReadiness: input.skillReadiness ?? {}, updatedAt: now };
+            return p;
+        }
+        case 'skill_upgrade_approved': {
+            const p = planBase(goalId, input.intent, '人工批准技能升级 → 回到可继续');
+            p.status = 'active';
+            p.continuation = {
+                skillReadiness: input.skillReadiness ?? { ok: true, at: now, reason: '人工批准技能升级' },
+                wakeReason: 'active',
+                autoContinue: true,
+                updatedAt: now,
+            };
+            p.evidence = [input.reason ?? `技能升级已被人工批准 (by ${by})`];
+            return p;
+        }
+        case 'external_wait_enter': {
+            const p = planBase(goalId, input.intent, `进入等外部回话: ${input.externalWait ?? ''}`.trim());
+            p.status = 'awaiting_external';
+            return p;
+        }
+        case 'external_wait_expired': {
+            const reason = input.reason || '外部等待超时 → 转人工';
+            const p = planBase(goalId, input.intent, reason);
+            p.status = 'needs_human';
+            p.continuation = {
+                wakeReason: 'needs_human',
+                needsExternal: undefined,
+                autoContinue: false,
+                lastExternalTimeout: reason,
+                updatedAt: now,
+            };
+            p.clearContinuationFields = ['needsExternal', 'external'];
+            p.evidence = [`外部事件超时 (by ${by}): ${reason}`];
+            return p;
+        }
+        case 'external_event_arrived': {
+            const p = planBase(goalId, input.intent, '外部事件到达 → 拉回 active (下一 tick 真执行)');
+            p.status = 'active';
+            p.continuation = {
+                wakeReason: 'active',
+                needsExternal: undefined,
+                autoContinue: true,
+                wakeAt: undefined,
+                updatedAt: now,
+            };
+            p.clearContinuationFields = ['needsExternal', 'external'];
+            return p;
+        }
+        case 'contact_revoked_human': {
+            const reason = input.revokeNote || '联系方式授权被撤销 → 该联系不可自动重试';
+            const p = planBase(goalId, input.intent, `转人工: ${reason}`);
+            p.status = 'needs_human';
+            p.continuation = {
+                wakeReason: 'needs_human',
+                needsExternal: undefined,
+                autoContinue: false,
+                updatedAt: now,
+            };
+            p.clearContinuationFields = ['needsExternal'];
+            p.evidence = [`联系方式授权撤销 (by ${by}): ${reason}`];
+            return p;
+        }
+        case 'criteria_needs_human': {
+            const reason = input.reason || '判据提不出来 (目标太模糊) → 交人';
+            const p = planBase(goalId, input.intent, reason);
+            p.status = 'needs_human';
+            p.evidence = [`判据生成失败 (by ${by}): ${reason}`];
+            return p;
+        }
+        /**
+         * 规则 ④ 的一条终止路径: 子 Agent 被阻塞且升级到父 → 交人。
+         * 旧写法在接线层直接 setContinuation + updateGoal(status) —— 那是绕过 Goal reducer 的状态写入。
+         */
+        case 'block_escalated_human': {
+            const reason = input.reason || '子 Agent 被阻塞且已升级 → 交人';
+            const p = planBase(goalId, input.intent, `阻塞升级转人工: ${reason}`);
+            p.status = 'needs_human';
+            p.continuation = {
+                state: 'needs_human',
+                autoContinue: false,
+                wakeReason: 'needs_human',
+                needsExternal: (input.needsExternalText ?? reason).slice(0, 300),
+                // 旧写法把未解决项写在 continuation 上 (Supervisor 下一轮读的就是这里) —— 语义不变, 两个落点都写
+                unresolvedItems: input.unresolvedItems ?? [],
+                updatedAt: now,
+            };
+            if (input.unresolvedItems)
+                p.unresolvedItems = input.unresolvedItems;
+            p.evidence = [`阻塞升级转人工 (by ${by}): ${reason}`];
+            return p;
+        }
+        case 'manual_wake': {
+            const p = planBase(goalId, input.intent, `人工唤醒: ${input.reason ?? '外部条件已满足'}`);
+            p.status = 'active';
+            p.continuation = {
+                wakeReason: 'active',
+                needsExternal: undefined,
+                autoContinue: true,
+                wakeAt: undefined,
+                updatedAt: now,
+            };
+            p.clearContinuationFields = ['needsExternal'];
+            return p;
+        }
+        /**
+         * 到点唤醒 (2026-09-25 M5 真跑补): `retry_wait` 的 `wakeAt` 到了 → 这个目标该跑了。
+         *
+         * 为什么必须**连状态一起写**: 旧写法 (Supervisor 的 `runGoal`) 只把 continuation 上的
+         * `wakeAt/wakeReason` 清掉, `goal.status` 仍停在 `retry_wait`。于是这条 Run 跑完、收尾判节奏时
+         * P0 读到的是**stale** 的 `goal.status=retry_wait` → 判 `wait`; 合并规则再把"等"落成
+         * `awaiting_external` (此时 wakeAt 已被清空 ⇒ 只能靠外部事件唤醒) —— 一个**刚跑出进展**的目标
+         * 就这样被挂起来, 界面显示"等待外部回复", 而没有任何人会再跑它。
+         * 真跑证据: P6-③ 时钟用例的阴性对照判红 (`repFast.executed=0`); 临时探针复现:
+         *   tick 后 `goal.status=awaiting_external / cont.state=awaiting_external / wakeAt=undefined`,
+         *   下一 tick 的跳过理由是 `awaiting_external: 等外部事件, 不重复发送`。
+         */
+        case 'scheduled_wake': {
+            const p = planBase(goalId, input.intent, input.reason ?? '到点唤醒 (wakeAt 已到) → 回到可继续');
+            p.status = 'active';
+            p.continuation = {
+                wakeReason: 'active',
+                wakeAt: undefined,
+                autoContinue: true,
+                state: 'active',
+                updatedAt: now,
+            };
+            return p;
+        }
+        default: {
+            // 穷举不完 = 有人加了 intent 忘了写计划 → 宁可拒绝也不静默
+            const never = input.intent;
+            return planBase(goalId, never, `未登记的意图: ${String(never)} → 拒绝改状态`);
+        }
+    }
+}
+/** 终态: 已终的 Goal 不许被非终态意图改回来 (历史不可改写) */
+const GOAL_TERMINAL = ['completed', 'failed', 'abandoned'];
+/**
+ * 把计划落盘。**全仓唯一的 Goal 状态写入出口**。
+ *
+ * 三条纪律:
+ *   ① 终态不可被非终态意图改回 (除了显式的人工意图); 已终的 Goal 不改写历史;
+ *   ② `completed` 必须过完成门 —— 门拒绝就退回 active 并**如实**记原因 (不许装作完成);
+ *   ③ 写失败不静默: 返回 ok=false + 原因, 由调用方原样记进 report/errors。
+ */
+export async function applyGoalStatePlan(plan) {
+    const res = {
+        ok: true, goalId: plan.goalId, intent: plan.intent, status: null, applied: [], reason: plan.reason,
+    };
+    const applied = res.applied;
+    const goal = await readGoal(plan.goalId).catch(() => null);
+    if (!goal) {
+        res.ok = false;
+        res.reason = `${plan.reason} (goal 不存在: ${plan.goalId})`;
+        return res;
+    }
+    // ① 终态保护: 已经完成的/失败的/放弃的目标不许被别的意图拉回来
+    const HUMAN_INTENTS = ['skill_upgrade_approved', 'manual_wake', 'user_revoked_goal'];
+    if (GOAL_TERMINAL.includes(goal.status) && plan.status && plan.status !== goal.status && !HUMAN_INTENTS.includes(plan.intent)) {
+        res.ok = false;
+        res.status = goal.status;
+        res.reason = `已终态 (${goal.status}) 不许被 ${plan.intent} 改写 → 拒绝 (历史不可改写)`;
+        return res;
+    }
+    // ② 完成门: completed 只有一条路
+    let effectiveStatus = plan.status;
+    if (plan.completionGate && plan.status === 'completed') {
+        const gate = await completeGoalIfEligible(plan.goalId).catch((err) => ({
+            ok: false, reason: `完成门自身失败: ${String(err?.message || err).slice(0, 160)}`, goal: null,
+        }));
+        if (!gate.ok) {
+            // 门拒绝 → 如实退回 active (保留原因), 不许装作完成
+            res.gateRejected = gate.reason;
+            effectiveStatus = 'active';
+            res.reason = `完成门拒绝 (${gate.reason}) → 退回 active`;
+            await setContinuation(plan.goalId, {
+                ...(plan.continuation ?? {}),
+                wakeReason: 'active',
+                autoContinue: true,
+                updatedAt: plan.continuation?.updatedAt ?? new Date().toISOString(),
+            }).then(() => applied.push('continuation:reject_rollback')).catch(() => null);
+            // 未解决项照旧记下来 (完成门说缺什么, 就写什么 —— 这是下一轮继续的依据, 不许丢)
+            const gateMissing = 'missing' in gate ? gate.missing : undefined;
+            if (gateMissing?.length) {
+                await setUnresolved(plan.goalId, gateMissing).then(() => applied.push('unresolved')).catch(() => null);
+            }
+            await updateGoal(plan.goalId, { status: 'active' }).then(() => applied.push('status:active')).catch(() => null);
+            res.status = (await readGoal(plan.goalId).catch(() => null))?.status ?? null;
+            return res;
+        }
+        applied.push('completion_gate:passed');
+        res.status = (await readGoal(plan.goalId).catch(() => null))?.status ?? null;
+        // ★ M5-⑥ (2026-09-25 真跑验收): 完成这条路**必须**把收尾 continuation 落盘。
+        //   旧写法 `if (plan.continuation.wakeReason !== 'completed')` 只在**不是**完成时写 —— 而走到
+        //   这里 (completionGate 通过) 的场景**恰好**就是 `wakeReason='completed'`
+        //   (`decideGoalOutcome` 的完成分支 + `mergeGoalOutcome` 的 complete 分支都写 'completed'),
+        //   于是这个条件在唯一需要它的时刻恒假 ⇒ 完成时**一条 continuation 都不写**:
+        //   盘上留着上一条 Run 的收尾记录 (`state:'active'` + 旧 `lastDecisionId` + 旧 `nextAction`),
+        //   而 `toUserVisibleState` 只读 continuation ⇒ **已完成**的 Goal 在界面/CLI 上显示"正在执行"
+        //   (界面比系统更乐观)。真跑证据 (`_probe-completion-continuation.ts`, 修前):
+        //   goal.status=completed 而 applied=['completion_gate:passed'] (无 continuation 写入) →
+        //   goalVisibleState='executing' (M5-⑨ 正向对照)。
+        //   完成门已经在这一步通过 (status 已真写 completed), 所以这里写的是**通过之后**的权威 continuation。
+        if (plan.continuation) {
+            await setContinuation(plan.goalId, plan.continuation).then(() => applied.push('continuation')).catch(() => null);
+        }
+        return res;
+    }
+    // ③ continuation (整片覆盖: 先清需要清的, 再写)
+    if (plan.continuation) {
+        const patch = { ...plan.continuation };
+        for (const f of plan.clearContinuationFields ?? []) {
+            if (!(f in patch))
+                patch[f] = undefined;
+        }
+        await setContinuation(plan.goalId, patch).then(() => applied.push('continuation')).catch(() => null);
+    }
+    // ④ 证据 / 未解决项
+    if (plan.evidence.length) {
+        await addEvidence(plan.goalId, plan.evidence).then(() => applied.push('evidence')).catch(() => null);
+    }
+    if (plan.unresolvedItems) {
+        await setUnresolved(plan.goalId, plan.unresolvedItems).then(() => applied.push('unresolved')).catch(() => null);
+    }
+    // ⑤ 状态本身
+    if (effectiveStatus && effectiveStatus !== goal.status) {
+        const patch = { status: effectiveStatus };
+        if (plan.resolution && effectiveStatus !== 'active')
+            patch.resolution = plan.resolution;
+        const next = await updateGoal(plan.goalId, patch).catch(() => null);
+        if (!next) {
+            res.ok = false;
+            res.reason = `${plan.reason} (状态写入失败: status=${effectiveStatus})`;
+        }
+        else {
+            applied.push(`status:${effectiveStatus}`);
+        }
+    }
+    else if (effectiveStatus) {
+        applied.push(`status:${effectiveStatus}(unchanged)`);
+    }
+    res.status = (await readGoal(plan.goalId).catch(() => null))?.status ?? effectiveStatus;
+    return res;
+}
+/** 意图 → 计划 → 落盘 (调用方只用这一个入口) */
+export async function reduceGoalState(input) {
+    return applyGoalStatePlan(planGoalStateChange(input));
+}
+// ============================================================================
+// §4. 给上层的只读辅助 (不写盘)
+// ============================================================================
+/**
+ * 这个 Goal 现在**允许**被哪个状态吗? (终态/等人态的边界查询)
+ *
+ * 存在的意义: 接线前的调用点各自手写 `!['completed','failed','abandoned'].includes(status)`,
+ * 六处写法不一致 (有的漏 abandoned)。收敛到一处, 由门断言只有这一处。
+ */
+export function goalAcceptsStatusChange(current, next, intent) {
+    if (current === next)
+        return { ok: true, reason: '状态未变' };
+    if (GOAL_TERMINAL.includes(current)) {
+        const allowedByHuman = ['skill_upgrade_approved', 'manual_wake', 'user_revoked_goal'];
+        if (!allowedByHuman.includes(intent)) {
+            return { ok: false, reason: `已终态 (${current}): ${intent} 不许改写` };
+        }
+    }
+    return { ok: true, reason: `${current} → ${next} (${intent})` };
+}

package/dist/agents/goal-store.js

@@ -18,6 +18,7 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import * as os from 'os';
 import * as crypto from 'crypto';
+import { toUserVisibleState } from './goal-flywheel/work-monitor.js';
 /** 可被 Supervisor 自动唤醒推进的状态 (其余必须等人或等外部事件) */
 export const GOAL_RUNNABLE_STATUSES = ['open', 'active', 'recovering', 'retry_wait', 'stalled'];
 export function goalsDir() {
@@ -131,6 +132,16 @@ export async function listGoals(opts = {}) {
     out.sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : -1));
     return typeof opts.limit === 'number' ? out.slice(0, opts.limit) : out;
 }
+/**
+ * 低层写入原语: 把 patch 合并进 goal.json。
+ *
+ * ★ 2026-09-25 (M0 接线冻结, 规则 ②「只有 Goal reducer 能改 Goal 状态」):
+ *   改 `status` 的**唯一**合法调用方是 `goal-state-reducer.ts` 的 `reduceGoalState`。
+ *   其他任何模块想改状态, 都必须表达成一个 intent 交给 reducer (它负责: 终态保护 /
+ *   完成门 / continuation 的唤醒语义 / 审计痕迹)。直接在这里写 status 会被
+ *   `src/test/goal-flywheel-m0-freeze.test.ts` 的源码级门判红 (按**文件**粒度扫, 不按行)。
+ *   非状态字段 (evidence / criteria / title ...) 仍可直接调本函数。
+ */
 export async function updateGoal(goalId, patch) {
     return withGoalLock(goalId, async () => {
         const rec = await readGoal(goalId);
@@ -520,7 +531,30 @@ export async function wakeReport(now = Date.now()) {
         }
         else if (live)
             wake = `已被 ${lease.owner} 认领`;
-        out.push({ goalId: g.goalId, status: g.status, wake, autoContinue: c?.autoContinue !== false, lease: live ? lease.owner : undefined });
+        // 用户视野: 只经 toUserVisibleState 映射; 阻塞明细由飞轮接线层的 collectWorkBlocks 提供
+        //   (这里传空阻塞表: goal-store 不读子工作目录, 保持单一事实来源)。
+        const visible = toUserVisibleState(continuationView(c, g.status), [], null);
+        out.push({ goalId: g.goalId, status: g.status, wake, autoContinue: c?.autoContinue !== false, lease: live ? lease.owner : undefined, visible, nextAction: c?.nextAction ?? '' });
     }
     return out;
 }
+/**
+ * 把 Goal 上收敛后的 continuation 读成冻结面 `GoalContinuationRecord`。
+ * 缺失字段按"没有"补默认值 —— 不许因为少一个字段就崩 (界面是只读视图)。
+ */
+function continuationView(c, status) {
+    if (!c)
+        return null;
+    return {
+        nextAction: c.nextAction ?? '',
+        wakeAt: c.wakeAt ?? null,
+        wakeReason: c.wakeReason ?? 'active',
+        autoContinue: c.autoContinue !== false,
+        requiredAgent: c.requiredAgent ?? null,
+        pendingReports: c.pendingReports ?? [],
+        unresolvedItems: c.unresolvedItems ?? [],
+        lastDecisionId: c.lastDecisionId ?? null,
+        state: c.state ?? (status === 'open' ? 'active' : status),
+        updatedAt: c.updatedAt ?? '',
+    };
+}

package/dist/agents/mobile-flywheel-view.js

@@ -0,0 +1,144 @@
+/**
+ * mobile-flywheel-view.ts — 「飞轮进度」的手机视图投影 (2026-09-25)
+ *
+ * 手机上新加的「飞轮进度」页**只读消费** `src/agents/goal-flywheel/*` 的冻结类型, 不造第二套状态:
+ *   · 用户可见状态 = `toUserVisibleState(continuation, blocks, decision)` (P3, 闭集五类)
+ *   · 五类的中英文案 = `USER_VISIBLE_STATE_LABELS` (冻结表)
+ *   · 阻塞建议动作 = `planBlockHandling` (P3, 不自动绕过 Harness)
+ *   · 汇报字段面 = `USER_REPORT_FIELDS` (P4b 的九字段) —— 视图里的 `report` 只允许出现这九个
+ *   · 内部字段 (lease / reducer / internal_status / retry_counter / worker_owner) **一律不出现**
+ *
+ * 本文件是纯函数 (不读钟、不做 I/O、不 import 任何 P4 之前的实现文件), 所以**桌面路由与手机 UI 可以共用一份**,
+ * 也就能被单测直接钉住"五类映射 + 不泄漏内部词"这两条。
+ *
+ * 刻意不做 (如实): 不读 lease / 不判"谁在跑" / 不显示 goalId·runId·workId·childAgentId (那是内部标识);
+ * 风险级别只透传 decision.riskLevel (高/中/低) 供 UI 提示"这一步需要你留意", 不据此自动做什么。
+ */
+import { toUserVisibleState, planBlockHandling } from './goal-flywheel/work-monitor.js';
+import { USER_VISIBLE_STATE_LABELS, USER_REPORT_FIELDS, MUST_NOT_EXPOSE_FIELDS, GOAL_TERMINAL_STATES, BLOCK_RESOLUTION_ACTIONS, } from './goal-flywheel/types.js';
+/** 已冻结: 汇报字段面 + 内部字段面 (这里再导出一次, 供视图/测试直接引用) */
+export { USER_REPORT_FIELDS, MUST_NOT_EXPOSE_FIELDS };
+// ── 呈现用文案 (只翻译冻结枚举值, 不新增状态) ────────────────────────────────
+export const BLOCK_OWNER_LABELS = {
+    parent: { zh: '由主任务处理', en: 'Handled by the main task' },
+    child: { zh: '由子任务处理', en: 'Handled by the sub-task' },
+    external: { zh: '等外部处理', en: 'Waiting on an external party' },
+    system: { zh: '由系统处理', en: 'Handled by the system' },
+    user: { zh: '要你来处理', en: 'Needs you' },
+};
+export const BLOCK_ACTION_LABELS = {
+    send_adjustment: { zh: '先发一次调整指令', en: 'Send an adjustment first' },
+    replace_child: { zh: '替换执行者', en: 'Replace the runner' },
+    takeover: { zh: '主任务接管', en: 'Main task takes over' },
+    request_report: { zh: '要求补齐报告', en: 'Request a complete report' },
+    escalate_parent: { zh: '上报主任务', en: 'Escalate to the main task' },
+    change_plan: { zh: '改计划', en: 'Change the plan' },
+    wait_dependency: { zh: '继续等', en: 'Keep waiting' },
+    needs_human: { zh: '转人工', en: 'Hand to a human' },
+};
+/** 阻塞类型 → 极短的人话 (只说"卡在哪一类", 不暴露内部字段名) */
+export const BLOCK_KIND_LABELS = {
+    no_heartbeat: { zh: '子任务没有心跳了', en: 'Sub-task stopped reporting' },
+    waiting_dependency: { zh: '在等依赖', en: 'Waiting on a dependency' },
+    repeated_failure: { zh: '反复失败', en: 'Repeated failures' },
+    no_progress: { zh: '活着但没进展', en: 'Alive but no progress' },
+    tool_blocked: { zh: '工具或资源被阻', en: 'Tool or resource blocked' },
+    budget_blocked: { zh: '预算用尽', en: 'Budget exhausted' },
+    permission_blocked: { zh: '权限不足', en: 'Permission missing' },
+    runner_unavailable: { zh: '没有可用执行器', en: 'No runner available' },
+    external_timeout: { zh: '等外部超时', en: 'External wait timed out' },
+    report_missing: { zh: '报告不完整或没回', en: 'Report missing or incomplete' },
+};
+function isoOrNull(v) {
+    if (typeof v !== 'string' || !v)
+        return null;
+    return Number.isFinite(Date.parse(v)) ? v : null;
+}
+function msSince(iso, now) {
+    const t = iso ? Date.parse(iso) : NaN;
+    return Number.isFinite(t) ? Math.max(0, now - t) : 0;
+}
+/**
+ * 飞轮进度 → 手机视图。
+ * `continuation` 为 null 时 (终态目标没有 continuation) 仍如实给出五类之一 + 结论,
+ * **不编造"正在执行"** (那正是 P3 要防的假象)。
+ */
+export function buildMobileFlywheelView(input) {
+    const now = Number.isFinite(input?.now) ? input.now : 0;
+    const continuation = input?.continuation ?? null;
+    // 终态**不由调用方口述**: 直接读冻结的 GOAL_TERMINAL_STATES, 与 toUserVisibleState 第 ② 步同一判据
+    const terminal = continuation !== null
+        && GOAL_TERMINAL_STATES.includes(continuation.state);
+    const allBlocks = Array.isArray(input?.blocks) ? input.blocks : [];
+    const decision = input?.decision ?? null;
+    // 冻结的映射: 用户可见状态只有一个来源
+    const visibleState = toUserVisibleState(continuation, allBlocks, decision);
+    const unresolved = allBlocks.filter((b) => b?.resolvedAt === null);
+    const blocks = unresolved.map((b) => {
+        // 冻结表里没有这个 kind / 调用抛错时, 页面也不能打崩 —— 退回线索里的建议动作, 再不行按"转人工"
+        let action;
+        try {
+            action = planBlockHandling(b);
+        }
+        catch {
+            action = BLOCK_RESOLUTION_ACTIONS.includes(String(b.suggestedAction))
+                ? b.suggestedAction
+                : 'needs_human';
+        }
+        return {
+            kind: b.kind,
+            kindLabel: BLOCK_KIND_LABELS[b.kind] || { zh: '未知阻塞', en: 'Unknown block' },
+            ownerLabel: BLOCK_OWNER_LABELS[b.owner] || { zh: '未知处理方', en: 'Unknown owner' },
+            suggestedAction: action,
+            actionLabel: BLOCK_ACTION_LABELS[action] || { zh: '转人工', en: 'Hand to a human' },
+            blockedForMs: msSince(b.blockedAt, now),
+            dependency: b.dependency ? String(b.dependency) : null,
+            note: String(b.note || ''),
+            escalationAt: isoOrNull(b.escalationAt),
+            lastProgressAt: typeof b.lastProgressAt === 'string' ? b.lastProgressAt : '',
+        };
+    });
+    const wakeAt = isoOrNull(continuation?.wakeAt);
+    // 终态目标不承诺"下次醒来" (即使记录里还留着旧的 wakeAt, 也不该让人以为还会醒)
+    const resumeInMs = terminal || !wakeAt ? null : Date.parse(wakeAt) - now;
+    const completed = (decision?.progressDelta?.newlyCompletedCriteria || []);
+    const evidence = (decision?.progressDelta?.newEvidence || []).map((e) => String(e)).slice(0, 10);
+    // 口径: continuation = **当前计划** (下一步/还剩什么/何时醒来); decision = **最近一次自述** (为什么/证据/已满足判据)。
+    // 所以还剩什么以继续记录为准, 没有才退回最近的决策记录。
+    const remaining = (continuation ? continuation.unresolvedItems : decision?.unresolvedItems || []).map((s) => String(s)).slice(0, 10);
+    const blockReasons = blocks.map((b) => `${b.kindLabel.zh} (${b.ownerLabel.zh}: ${b.actionLabel.zh})`);
+    const nextStep = String(continuation?.nextAction || decision?.nextAction || '').trim()
+        || (terminal ? '已经结束了 —— 看看结论, 决定要不要立新目标' : '（还没有写下下一步 —— 这本身就是要人看一眼的信号）');
+    const conclusion = decision?.reason
+        ? String(decision.reason)
+        : (terminal ? '这个目标已经结束' : String(continuation?.wakeReason || ''));
+    const exposed = ['conclusion', 'completed', 'evidence', 'remaining', 'blockReasons', 'nextStep', 'willContinue', 'expectedResumeAt', 'visibleState'];
+    const report = {
+        conclusion,
+        completed: completed.map((i) => `判据 #${i}`),
+        evidence,
+        remaining,
+        blockReasons,
+        nextStep,
+        willContinue: continuation?.autoContinue === true,
+        expectedResumeAt: wakeAt,
+        visibleState,
+        exposedFields: exposed,
+        generatedAt: new Date(now).toISOString(),
+    };
+    return {
+        visibleState,
+        stateLabel: USER_VISIBLE_STATE_LABELS[visibleState],
+        report,
+        blocks,
+        resumeInMs,
+        requiredAgent: continuation?.requiredAgent ? `指定执行者: ${String(continuation.requiredAgent).slice(0, 24)}` : null,
+        riskLevel: decision?.riskLevel ?? null,
+        generatedAt: new Date(now).toISOString(),
+    };
+}
+/** 视图里是否含内部字段名 (单测/门: 必须为空) */
+export function findInternalFieldLeaks(text) {
+    const t = String(text ?? '');
+    return MUST_NOT_EXPOSE_FIELDS.filter((f) => t.includes(f));
+}