hyacinth-ai 0.9.6

package/dist/flow/todo-flow.js

@@ -0,0 +1,107 @@
+// ============================================================
+// TodoFlow — 任务拆分与逐步执行 Flow
+// ============================================================
+//
+// 两阶段动态 Flow：
+//   1. Planning — 模型调用 activate_todo 激活 → 注入分析提示词
+//      → 模型调用 add_todo_step 添加步骤 → complete_flow_step 完成规划
+//   2. Execution — 框架逐步骤注入执行提示词
+//      → 模型完成每步后调用 complete_flow_step → 自动推进
+// ============================================================
+import { loadPrompt } from '../prompts/loader.js';
+export class TodoFlow {
+    id = 'todo';
+    status = 'idle';
+    currentStepIndex = 0;
+    phase = 'planning';
+    steps = [];
+    task = '';
+    stepCounter = 0;
+    planningPrompt;
+    executionPromptTemplate;
+    constructor() {
+        this.planningPrompt = loadPrompt('flows/todo-planning');
+        this.executionPromptTemplate = loadPrompt('flows/todo-execution');
+    }
+    activate(context) {
+        this.task = context?.task ?? '';
+        this.steps = [];
+        this.stepCounter = 0;
+        this.currentStepIndex = 0;
+        this.phase = 'planning';
+        this.status = 'active';
+    }
+    deactivate() {
+        this.status = 'idle';
+        this.steps = [];
+        this.task = '';
+        this.phase = 'planning';
+    }
+    getSteps() {
+        return this.steps;
+    }
+    getCurrentStep() {
+        if (this.status !== 'active')
+            return null;
+        if (this.phase === 'planning')
+            return null; // 规划阶段没有"当前步骤"
+        return this.steps[this.currentStepIndex] ?? null;
+    }
+    addStep(description) {
+        if (this.phase !== 'planning') {
+            throw new Error('Cannot add steps outside planning phase');
+        }
+        this.stepCounter++;
+        const step = {
+            id: `todo-step-${this.stepCounter}`,
+            prompt: description,
+        };
+        this.steps.push(step);
+        return step;
+    }
+    clearSteps() {
+        this.steps = [];
+        this.stepCounter = 0;
+    }
+    advance() {
+        if (this.phase === 'planning') {
+            // 规划完成 → 进入执行阶段
+            if (this.steps.length === 0)
+                return false; // 没有步骤，直接结束
+            this.phase = 'execution';
+            this.currentStepIndex = 0;
+            return true;
+        }
+        // 执行阶段：推进到下一步
+        this.currentStepIndex++;
+        return !this.isComplete();
+    }
+    isComplete() {
+        if (this.phase === 'planning')
+            return false;
+        return this.currentStepIndex >= this.steps.length;
+    }
+    getInjection() {
+        if (this.status !== 'active')
+            return null;
+        if (this.phase === 'planning') {
+            return this.buildPlanningInjection();
+        }
+        // 执行阶段：注入当前步骤
+        const step = this.getCurrentStep();
+        if (!step)
+            return null;
+        return this.buildExecutionInjection(step);
+    }
+    buildPlanningInjection() {
+        return this.planningPrompt.replace(/\{\{task\}\}/g, this.task || '(no task provided)');
+    }
+    buildExecutionInjection(step) {
+        return this.executionPromptTemplate
+            .replace(/\{\{task\}\}/g, this.task)
+            .replace(/\{\{current\}\}/g, String(this.currentStepIndex + 1))
+            .replace(/\{\{total\}\}/g, String(this.steps.length))
+            .replace(/\{\{description\}\}/g, step.prompt);
+    }
+}
+//# sourceMappingURL=todo-flow.js.map

package/dist/flow/types.d.ts

@@ -0,0 +1,78 @@
+/** 单个流程步骤 */
+export interface FlowStep {
+    /** 步骤标识符（全局唯一） */
+    id: string;
+    /** 注入给模型的提示词文本 */
+    prompt: string;
+}
+/** Flow 状态 */
+export type FlowStatus = 'idle' | 'active' | 'completed';
+/** Flow 阶段（动态 Flow 使用） */
+export type FlowPhase = 'planning' | 'execution';
+/**
+ * FlowController — 流程控制器接口。
+ *
+ * 具体实现：
+ *   - BootstrapFlow — 固定步骤（预定义 4 步）
+ *   - TodoFlow — 动态步骤（模型运行时定义步骤）
+ */
+export interface FlowController {
+    /** 唯一标识，如 'bootstrap'、'todo' */
+    readonly id: string;
+    /** 当前状态 */
+    status: FlowStatus;
+    /** 当前步骤索引（0-based） */
+    currentStepIndex: number;
+    /** 激活 Flow */
+    activate(): void;
+    /** 停用 Flow */
+    deactivate(): void;
+    /** 获取所有步骤 */
+    getSteps(): FlowStep[];
+    /** 获取当前步骤，无则返回 null */
+    getCurrentStep(): FlowStep | null;
+    /**
+     * 推进到下一步。
+     * @returns true=还有后续步骤, false=所有步骤已完成
+     */
+    advance(): boolean;
+    /** 是否已完成所有步骤 */
+    isComplete(): boolean;
+    /**
+     * 获取当前注入文本。
+     * compose 时由 Zone 5 的 flow_injection section 调用。
+     * @returns 当前步骤的提示词，若未激活则返回 null
+     */
+    getInjection(): string | null;
+    /** 完成回调（由 FlowRegistry 在 advance 返回 false 时调用） */
+    onComplete?(): Promise<void> | void;
+}
+/**
+ * MutableFlowController — 支持动态步骤的 Flow。
+ *
+ * 用于 TODO 等场景，模型在运行时通过 add_todo_step 工具添加步骤。
+ */
+export interface MutableFlowController extends FlowController {
+    /** 当前阶段 */
+    phase: FlowPhase;
+    /**
+     * 激活 Flow（带参数）。
+     * @param context 激活上下文（如 TODO 的任务描述）
+     */
+    activate(context?: Record<string, unknown>): void;
+    /** 添加一个步骤（仅在 planning 阶段有效） */
+    addStep(description: string): FlowStep;
+    /** 清空所有步骤 */
+    clearSteps(): void;
+}
+/** FlowRegistry 接口 */
+export interface IFlowRegistry {
+    register(flow: FlowController): void;
+    get(id: string): FlowController | undefined;
+    getActive(): FlowController | undefined;
+    activate(id: string, context?: Record<string, unknown>): void;
+    deactivate(): void;
+    /** 当前活跃 Flow 推进一步，若完成则自动 deactivate */
+    onStepComplete(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/flow/types.js

@@ -0,0 +1,12 @@
+// ============================================================
+// Flow Control — 核心类型
+// ============================================================
+//
+// FlowController 是框架级流程控制的抽象。
+// 一个 Flow 管理一组有序步骤，在每轮 compose 时注入当前步骤的
+// 提示词到 Zone 5，并在检测到步骤完成信号后自动推进。
+//
+// 同一时间只有一个 Flow 处于活跃状态。
+// ============================================================
+export {};
+//# sourceMappingURL=types.js.map

package/dist/flows/bootstrap.d.ts

@@ -0,0 +1,18 @@
+import type { MachineContext, MachineSnapshot, AdvanceResult } from '../machine/types.js';
+import { MachineRunner } from '../machine/runner.js';
+import type { FlowController } from './types.js';
+export declare class BootstrapFlow implements FlowController {
+    readonly id = "bootstrap";
+    readonly runner: MachineRunner;
+    private personaDir;
+    private stepPrompts;
+    constructor(personaDir: string);
+    activate(_context?: MachineContext): void;
+    deactivate(): void;
+    advance(event: string): AdvanceResult;
+    getSnapshot(): MachineSnapshot;
+    isComplete(): boolean;
+    getInjection(): string | null;
+    private loadPromptOnce;
+}
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/flows/bootstrap.js

@@ -0,0 +1,119 @@
+// ============================================================
+// BootstrapFlow — 身份引导 Flow
+// ============================================================
+//
+// 首次安装后自动运行一次。通过 4 个步骤引导模型与用户交流，
+// 逐步填写 SOUL.md、IDENTITY.md、USER.md，完成后永久标记。
+//
+// 基于 MachineDef：4 个固定状态，线性推进，无 guard，无动态步骤。
+// 步骤提示词从 src/prompts/flows/bootstrap-*.md 加载。
+// ============================================================
+import { MachineRunner } from '../machine/runner.js';
+import { loadPrompt } from '../prompts/loader.js';
+import { markBootstrapComplete } from '../setup/persona-bootstrap.js';
+// ── 步骤定义 ────────────────────────────────────────────────
+const STEP_FILES = [
+    'bootstrap-soul',
+    'bootstrap-identity',
+    'bootstrap-user',
+    'bootstrap-confirm',
+];
+const STATE_NAMES = ['soul', 'identity', 'user', 'confirm'];
+// ── MachineDef ──────────────────────────────────────────────
+/**
+ * Bootstrap 状态机定义。
+ *
+ * States:  soul → identity → user → confirm → __completed__
+ * Initial: soul
+ * Terminal: __completed__
+ *
+ * 线性推进，无 guard——每步的 complete_flow_step 无条件转移。
+ * 最后一步 (confirm → __completed__) 的 onTransition 中调用
+ * markBootstrapComplete() 做永久标记。
+ */
+function createBootstrapMachineDef(personaDir) {
+    return {
+        id: 'bootstrap',
+        initial: 'soul',
+        states: {
+            soul: { label: '设定灵魂' },
+            identity: { label: '设定身份' },
+            user: { label: '了解用户' },
+            confirm: { label: '确认配置' },
+            __completed__: { label: '已完成' },
+        },
+        transitions: [
+            { from: 'soul', to: 'identity', event: 'complete_flow_step' },
+            { from: 'identity', to: 'user', event: 'complete_flow_step' },
+            { from: 'user', to: 'confirm', event: 'complete_flow_step' },
+            {
+                from: 'confirm',
+                to: '__completed__',
+                event: 'complete_flow_step',
+            },
+        ],
+        terminalStates: ['__completed__'],
+        onComplete: async (_ctx) => {
+            await markBootstrapComplete(personaDir);
+        },
+    };
+}
+// ── BootstrapFlow ────────────────────────────────────────────
+export class BootstrapFlow {
+    id = 'bootstrap';
+    runner;
+    personaDir;
+    stepPrompts = new Map();
+    constructor(personaDir) {
+        this.personaDir = personaDir;
+        this.runner = new MachineRunner(createBootstrapMachineDef(personaDir));
+    }
+    // ── 生命周期 ──────────────────────────────────────────────
+    activate(_context) {
+        // Bootstrap 不需要 context——步骤是固定的
+        this.runner.activate();
+    }
+    deactivate() {
+        this.runner.deactivate();
+    }
+    advance(event) {
+        return this.runner.advance(event);
+    }
+    getSnapshot() {
+        return this.runner.getSnapshot();
+    }
+    isComplete() {
+        return this.runner.isComplete();
+    }
+    // ── Zone 5 注入 ───────────────────────────────────────────
+    getInjection() {
+        const snap = this.runner.getSnapshot();
+        if (snap.status !== 'active')
+            return null;
+        // 从状态名映射到步骤文件
+        const stateToFile = {
+            soul: 'bootstrap-soul',
+            identity: 'bootstrap-identity',
+            user: 'bootstrap-user',
+            confirm: 'bootstrap-confirm',
+        };
+        const fileKey = stateToFile[snap.currentState];
+        if (!fileKey)
+            return null;
+        // 懒加载提示词
+        const prompt = this.loadPromptOnce(fileKey)
+            .replace(/\{\{personaDir\}\}/g, this.personaDir);
+        const stepIndex = STATE_NAMES.indexOf(snap.currentState);
+        const stepNum = stepIndex >= 0 ? stepIndex + 1 : 1;
+        const header = `\n[Bootstrap ${stepNum}/4]\n`;
+        return header + prompt;
+    }
+    // ── 内部 ──────────────────────────────────────────────────
+    loadPromptOnce(file) {
+        if (!this.stepPrompts.has(file)) {
+            this.stepPrompts.set(file, loadPrompt(`flows/${file}`));
+        }
+        return this.stepPrompts.get(file);
+    }
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/flows/index.d.ts

@@ -0,0 +1,6 @@
+export { MachineRegistry } from '../machine/registry.js';
+export type { FlowController } from './types.js';
+export { TodoFlow } from './todo.js';
+export { BootstrapFlow } from './bootstrap.js';
+export { createCompleteFlowStepTool, createActivateTodoTool, createAddTodoStepTool, isFlowTool, } from './tools.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/flows/index.js

@@ -0,0 +1,11 @@
+// ============================================================
+// Flows — 桶导出
+// ============================================================
+// 从 machine 层透出（统一入口）
+export { MachineRegistry } from '../machine/registry.js';
+// Flow 实现
+export { TodoFlow } from './todo.js';
+export { BootstrapFlow } from './bootstrap.js';
+// 工具
+export { createCompleteFlowStepTool, createActivateTodoTool, createAddTodoStepTool, isFlowTool, } from './tools.js';
+//# sourceMappingURL=index.js.map

package/dist/flows/todo.d.ts

@@ -0,0 +1,26 @@
+import type { MachineContext, MachineSnapshot, AdvanceResult } from '../machine/types.js';
+import { MachineRunner } from '../machine/runner.js';
+import type { FlowController } from './types.js';
+interface TodoStep {
+    id: string;
+    prompt: string;
+}
+export declare class TodoFlow implements FlowController {
+    readonly id = "todo";
+    readonly runner: MachineRunner;
+    private planningPrompt;
+    private executionPromptTemplate;
+    private stepCounter;
+    constructor();
+    activate(context?: MachineContext): void;
+    deactivate(): void;
+    advance(event: string): AdvanceResult;
+    getSnapshot(): MachineSnapshot;
+    isComplete(): boolean;
+    /** 向 TODO 计划添加一个执行步骤（仅在 planning 阶段有效） */
+    addStep(description: string): TodoStep;
+    /** Zone 5 注入文本 */
+    getInjection(): string | null;
+}
+export {};
+//# sourceMappingURL=todo.d.ts.map

package/dist/flows/todo.js

@@ -0,0 +1,174 @@
+// ============================================================
+// TodoFlow — 任务拆分与逐步执行 Flow
+// ============================================================
+//
+// 基于 MachineDef 的两阶段动态 Flow：
+//   1. Planning — 模型调用 add_todo_step 添加步骤（ctx 突变）
+//      → complete_flow_step（guard: steps.length > 0）进入执行阶段
+//   2. Executing — 模型逐步完成每步
+//      → complete_flow_step（guard: hasMoreSteps）推进 stepIndex
+//      → complete_flow_step（guard: isLastStep）进入终端
+//
+// 关键设计：
+//   - add_todo_step 是 context 突变，不触发状态转移（绕过 guard）
+//   - complete_flow_step 是事件，触发 guard → 转移
+//   - Guard 失败时 reason 通过工具返回值反馈给模型
+// ============================================================
+import { MachineRunner } from '../machine/runner.js';
+import { loadPrompt } from '../prompts/loader.js';
+// ── MachineDef ──────────────────────────────────────────────
+/**
+ * TODO 状态机定义。
+ *
+ * States:  planning | executing | __completed__
+ * Initial: planning
+ * Terminal: __completed__
+ *
+ * 转移表（按优先级排列——先匹配的 guard 通过即执行）：
+ *   1. planning   + complete → executing     (guard: steps.length > 0)
+ *   2. planning   + complete → __completed__  (guard: steps.length === 0)
+ *   3. executing  + complete → executing     (guard: hasMoreSteps, onTransition: stepIndex++)
+ *   4. executing  + complete → __completed__  (guard: isLastStep)
+ */
+function createTodoMachineDef() {
+    return {
+        id: 'todo',
+        initial: 'planning',
+        states: {
+            planning: { label: '规划中' },
+            executing: { label: '执行中' },
+            __completed__: { label: '已完成' },
+        },
+        transitions: [
+            // planning → executing：必须有步骤
+            {
+                from: 'planning',
+                to: 'executing',
+                event: 'complete_flow_step',
+                guard: (ctx) => {
+                    const steps = ctx.steps ?? [];
+                    if (steps.length === 0) {
+                        return { ok: false, reason: 'No steps defined. Use add_todo_step to add steps before completing planning.' };
+                    }
+                    return { ok: true };
+                },
+                onTransition: (ctx) => {
+                    // 重置 stepIndex 到第 0 步
+                    ctx.stepIndex = 0;
+                },
+            },
+            // planning → __completed__：没有步骤直接结束
+            {
+                from: 'planning',
+                to: '__completed__',
+                event: 'complete_flow_step',
+                guard: (ctx) => {
+                    const steps = ctx.steps ?? [];
+                    return { ok: steps.length === 0 };
+                },
+            },
+            // executing → executing：还有更多步骤（self-transition）
+            {
+                from: 'executing',
+                to: 'executing',
+                event: 'complete_flow_step',
+                guard: (ctx) => {
+                    const steps = ctx.steps ?? [];
+                    const idx = ctx.stepIndex ?? 0;
+                    if (idx + 1 >= steps.length) {
+                        return { ok: false, reason: 'This is the last step.' };
+                    }
+                    return { ok: true };
+                },
+                onTransition: (ctx) => {
+                    ctx.stepIndex = (ctx.stepIndex ?? 0) + 1;
+                },
+            },
+            // executing → __completed__：最后一步完成
+            {
+                from: 'executing',
+                to: '__completed__',
+                event: 'complete_flow_step',
+                guard: (ctx) => {
+                    const steps = ctx.steps ?? [];
+                    const idx = ctx.stepIndex ?? 0;
+                    return { ok: idx + 1 >= steps.length };
+                },
+            },
+        ],
+        terminalStates: ['__completed__'],
+    };
+}
+// ── TodoFlow ─────────────────────────────────────────────────
+export class TodoFlow {
+    id = 'todo';
+    runner;
+    planningPrompt;
+    executionPromptTemplate;
+    stepCounter = 0;
+    constructor() {
+        this.planningPrompt = loadPrompt('flows/todo-planning');
+        this.executionPromptTemplate = loadPrompt('flows/todo-execution');
+        this.runner = new MachineRunner(createTodoMachineDef());
+    }
+    // ── 生命周期 ──────────────────────────────────────────────
+    activate(context) {
+        this.stepCounter = 0;
+        this.runner.activate({
+            task: context?.task ?? '',
+            steps: [],
+            stepIndex: 0,
+        });
+    }
+    deactivate() {
+        this.runner.deactivate();
+    }
+    advance(event) {
+        return this.runner.advance(event);
+    }
+    getSnapshot() {
+        return this.runner.getSnapshot();
+    }
+    isComplete() {
+        return this.runner.isComplete();
+    }
+    // ── 业务方法 ──────────────────────────────────────────────
+    /** 向 TODO 计划添加一个执行步骤（仅在 planning 阶段有效） */
+    addStep(description) {
+        const snap = this.runner.getSnapshot();
+        if (snap.currentState !== 'planning') {
+            throw new Error('Cannot add steps outside planning phase');
+        }
+        this.stepCounter++;
+        const step = {
+            id: `todo-step-${this.stepCounter}`,
+            prompt: description,
+        };
+        const steps = [...(snap.context.steps ?? []), step];
+        this.runner.updateContext({ steps });
+        return step;
+    }
+    /** Zone 5 注入文本 */
+    getInjection() {
+        const snap = this.runner.getSnapshot();
+        if (snap.status !== 'active')
+            return null;
+        if (snap.currentState === 'planning') {
+            return this.planningPrompt.replace(/\{\{task\}\}/g, snap.context.task || '(no task provided)');
+        }
+        if (snap.currentState === 'executing') {
+            const steps = snap.context.steps ?? [];
+            const idx = snap.context.stepIndex ?? 0;
+            const step = steps[idx];
+            if (!step)
+                return null;
+            return this.executionPromptTemplate
+                .replace(/\{\{task\}\}/g, snap.context.task || '')
+                .replace(/\{\{current\}\}/g, String(idx + 1))
+                .replace(/\{\{total\}\}/g, String(steps.length))
+                .replace(/\{\{description\}\}/g, step.prompt);
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=todo.js.map

package/dist/flows/tools.d.ts

@@ -0,0 +1,8 @@
+import type { Tool } from '../tools/interface.js';
+import type { MachineRegistry } from '../machine/registry.js';
+/** 判断给定工具名是否为 Flow 框架工具 */
+export declare function isFlowTool(name: string): boolean;
+export declare function createCompleteFlowStepTool(registry: MachineRegistry): Tool;
+export declare function createActivateTodoTool(registry: MachineRegistry): Tool;
+export declare function createAddTodoStepTool(registry: MachineRegistry): Tool;
+//# sourceMappingURL=tools.d.ts.map