hyacinth-ai 0.9.6

package/dist/machine/flows/spec.js

@@ -0,0 +1,176 @@
+// ============================================================
+// SpecFlow — 需求规格 → 执行 → 验证 Flow
+// ============================================================
+//
+// 三阶段：
+//   1. define            — 一份提示词，同时写出 spec.md + tasks.md + checklist.md
+//   2. executing_tasks    — 逐条解析 tasks.md 的 - [ ]，注入 → 标记 [x] → 推进
+//   3. executing_checklist — 逐条解析 checklist.md 的 - [ ]，注入 → 标记 [x] → 推进
+//
+// Guard 通过解析文件中的 [ ]/[x] 状态判断是否全部完成。
+// ============================================================
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { MachineRunner } from '../runner.js';
+import { loadPrompt } from '../../prompts/loader.js';
+/** 解析 markdown 中的 - [ ] / - [x] 条目 */
+function parseCheckItems(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const items = [];
+        for (const line of content.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed.startsWith('- [x]') || trimmed.startsWith('- [X]')) {
+                items.push({ line: trimmed, checked: true });
+            }
+            else if (trimmed.startsWith('- [ ]')) {
+                items.push({ line: trimmed, checked: false });
+            }
+        }
+        return items;
+    }
+    catch {
+        return [];
+    }
+}
+/** 获取 spec 目录路径 */
+function specDir(ctx) {
+    return ctx.specDir || path.join(process.cwd(), '.agent', 'specs', ctx.task || 'unknown');
+}
+/** 从 tasks/checklist 抽取条目列表（给 getInjection 用） */
+function formatItemList(items) {
+    return items.map((it, i) => {
+        const marker = it.checked ? '[x]' : '[ ]';
+        return `${i + 1}. ${marker} ${it.line.replace(/^-\s*\[.\]\s*/, '')}`;
+    }).join('\n');
+}
+/** 找第一个未完成的条目 */
+function firstUnchecked(items) {
+    const item = items.find(it => !it.checked);
+    return item ? item.line.replace(/^-\s*\[.\]\s*/, '') : '';
+}
+// ── MachineDef ──────────────────────────────────────────────
+function createSpecMachineDef() {
+    return {
+        id: 'spec',
+        initial: 'define',
+        states: {
+            define: { label: '撰写文档' },
+            executing_tasks: { label: '执行任务' },
+            executing_checklist: { label: '验收检查' },
+            __completed__: { label: '已完成' },
+        },
+        transitions: [
+            // define → executing_tasks
+            { from: 'define', to: 'executing_tasks', event: 'flow_complete' },
+            // executing_tasks → executing_tasks（还有未完成任务）
+            {
+                from: 'executing_tasks', to: 'executing_tasks', event: 'flow_complete',
+                guard: (ctx) => {
+                    const items = parseCheckItems(path.join(specDir(ctx), 'tasks.md'));
+                    return { ok: items.some(i => !i.checked), reason: 'All tasks completed — moving to checklist verification.' };
+                },
+            },
+            // executing_tasks → executing_checklist（全部完成）
+            {
+                from: 'executing_tasks', to: 'executing_checklist', event: 'flow_complete',
+                guard: (ctx) => {
+                    const items = parseCheckItems(path.join(specDir(ctx), 'tasks.md'));
+                    return { ok: items.length > 0 && items.every(i => i.checked) };
+                },
+            },
+            // executing_checklist → executing_checklist（还有未验证项）
+            {
+                from: 'executing_checklist', to: 'executing_checklist', event: 'flow_complete',
+                guard: (ctx) => {
+                    const items = parseCheckItems(path.join(specDir(ctx), 'checklist.md'));
+                    return { ok: items.some(i => !i.checked), reason: 'All checklist items verified — flow complete.' };
+                },
+            },
+            // executing_checklist → __completed__（全部验证通过）
+            {
+                from: 'executing_checklist', to: '__completed__', event: 'flow_complete',
+                guard: (ctx) => {
+                    const items = parseCheckItems(path.join(specDir(ctx), 'checklist.md'));
+                    return { ok: items.length > 0 && items.every(i => i.checked) };
+                },
+            },
+        ],
+        terminalStates: ['__completed__'],
+    };
+}
+// ── SpecFlow ─────────────────────────────────────────────────
+export class SpecFlow {
+    id = 'spec';
+    runner;
+    prompts = new Map();
+    constructor() {
+        this.runner = new MachineRunner(createSpecMachineDef());
+    }
+    // ── 生命周期 ──────────────────────────────────────────────
+    activate(context) {
+        const task = context?.task ?? '';
+        const dir = path.join(process.cwd(), '.agent', 'specs', task.replace(/[<>:"/\\|?*]/g, '-'));
+        this.runner.activate({ task, specDir: dir });
+    }
+    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 dir = specDir(snap.context);
+        const task = snap.context.task || '';
+        switch (snap.currentState) {
+            case 'define': {
+                const prompt = this.loadPrompt('spec-define')
+                    .replace(/\{\{task\}\}/g, task)
+                    .replace(/\{\{specDir\}\}/g, dir);
+                return `\n[Spec: 撰写文档]\n${prompt}`;
+            }
+            case 'executing_tasks': {
+                const items = parseCheckItems(path.join(dir, 'tasks.md'));
+                const current = firstUnchecked(items);
+                const list = formatItemList(items);
+                const prompt = this.loadPrompt('spec-executing-tasks')
+                    .replace(/\{\{task\}\}/g, task)
+                    .replace(/\{\{item_list\}\}/g, list)
+                    .replace(/\{\{current_item\}\}/g, current || '(all done)');
+                const done = items.filter(i => i.checked).length;
+                return `\n[Spec: 执行任务 ${done}/${items.length}]\n${prompt}`;
+            }
+            case 'executing_checklist': {
+                const items = parseCheckItems(path.join(dir, 'checklist.md'));
+                const current = firstUnchecked(items);
+                const list = formatItemList(items);
+                const prompt = this.loadPrompt('spec-executing-checklist')
+                    .replace(/\{\{task\}\}/g, task)
+                    .replace(/\{\{item_list\}\}/g, list)
+                    .replace(/\{\{current_item\}\}/g, current || '(all done)');
+                const done = items.filter(i => i.checked).length;
+                return `\n[Spec: 验收检查 ${done}/${items.length}]\n${prompt}`;
+            }
+            default:
+                return null;
+        }
+    }
+    // ── 内部 ──────────────────────────────────────────────────
+    loadPrompt(file) {
+        if (!this.prompts.has(file)) {
+            this.prompts.set(file, loadPrompt(`flows/${file}`));
+        }
+        return this.prompts.get(file);
+    }
+}
+//# sourceMappingURL=spec.js.map

package/dist/machine/flows/todo.d.ts

@@ -0,0 +1,26 @@
+import type { MachineContext, MachineSnapshot, AdvanceResult } from '../types.js';
+import { MachineRunner } from '../runner.js';
+import type { FlowController } from './types.js';
+interface TodoStep {
+    id: string;
+    label: 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 阶段有效） */
+    addItem(description: string): TodoStep;
+    /** Zone 5 注入文本 */
+    getInjection(): string | null;
+}
+export {};
+//# sourceMappingURL=todo.d.ts.map

package/dist/machine/flows/todo.js

@@ -0,0 +1,175 @@
+// ============================================================
+// TodoFlow — 任务拆分与逐步执行 Flow
+// ============================================================
+//
+// 基于 MachineDef 的两阶段动态 Flow：
+//   1. Planning — 模型调用 flow_add 添加步骤（ctx 突变）
+//      → flow_complete（guard: steps.length > 0）进入执行阶段
+//   2. Executing — 模型逐步完成每步
+//      → flow_complete（guard: hasMoreSteps）推进 stepIndex
+//      → flow_complete（guard: isLastStep）进入终端
+//
+// 关键设计：
+//   - flow_add 是 context 突变，不触发状态转移（绕过 guard）
+//   - flow_complete 是事件，触发 guard → 转移
+//   - Guard 失败时 reason 通过工具返回值反馈给模型
+// ============================================================
+import { MachineRunner } from '../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: 'flow_complete',
+                guard: (ctx) => {
+                    const steps = ctx.steps ?? [];
+                    if (steps.length === 0) {
+                        return { ok: false, reason: 'No steps defined. Use flow_add to add steps before completing planning.' };
+                    }
+                    return { ok: true };
+                },
+                onTransition: (ctx) => {
+                    // 重置 stepIndex 到第 0 步
+                    ctx.stepIndex = 0;
+                },
+            },
+            // planning → __completed__：没有步骤直接结束
+            {
+                from: 'planning',
+                to: '__completed__',
+                event: 'flow_complete',
+                guard: (ctx) => {
+                    const steps = ctx.steps ?? [];
+                    return { ok: steps.length === 0 };
+                },
+            },
+            // executing → executing：还有更多步骤（self-transition）
+            {
+                from: 'executing',
+                to: 'executing',
+                event: 'flow_complete',
+                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: 'flow_complete',
+                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 阶段有效） */
+    addItem(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}`,
+            label: 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.label);
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=todo.js.map

package/dist/machine/flows/tools.d.ts

@@ -0,0 +1,8 @@
+import type { Tool } from '../../tools/interface.js';
+import type { MachineRegistry } from '../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

package/dist/machine/flows/tools.js

@@ -0,0 +1,119 @@
+// ============================================================
+// Flow Tools — 流程控制工具
+// ============================================================
+//
+// complete_flow_step  — 完成当前步骤，推进状态机（触发 guard 检查）
+// activate_todo       — 激活 TODO 模式，开始任务拆分
+// add_todo_step       — 向 TODO Flow 添加执行步骤（ctx 突变，非转移）
+//
+// Flow 工具不记入对话历史——状态由 Zone 5 注入体现。
+// ============================================================
+/** Flow 框架工具名称集合 — 这些工具不记入对话历史 */
+const FLOW_TOOL_NAMES = new Set([
+    'complete_flow_step',
+    'activate_todo',
+    'add_todo_step',
+]);
+/** 判断给定工具名是否为 Flow 框架工具 */
+export function isFlowTool(name) {
+    return FLOW_TOOL_NAMES.has(name);
+}
+// ── complete_flow_step ───────────────────────────────────────
+export function createCompleteFlowStepTool(registry) {
+    return {
+        name: 'complete_flow_step',
+        description: 'Complete the current flow step and advance to the next one. Call this when you have finished the current step\'s task. In TODO planning phase, this finishes planning and starts execution. In execution phase or bootstrap, this advances to the next step. If this is the final step, the flow ends.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+        async execute(_args) {
+            const active = registry.getActive();
+            if (!active) {
+                return 'No active flow. Nothing to complete.';
+            }
+            const snap = active.getSnapshot();
+            const isTodoPlanning = active.id === 'todo' && snap.currentState === 'planning';
+            const steps = snap.context.steps ?? [];
+            const idx = snap.context.stepIndex ?? 0;
+            const currentStep = steps[idx];
+            const stepLabel = currentStep
+                ? `"${currentStep.id}" (step ${idx + 1}/${steps.length})`
+                : isTodoPlanning
+                    ? 'planning phase'
+                    : `step ${idx + 1}`;
+            if (isTodoPlanning) {
+                const stepCount = steps.length;
+                if (stepCount === 0) {
+                    return 'Planning acknowledged. No steps defined — flow will end.';
+                }
+                return `Planning acknowledged. ${stepCount} steps defined, transitioning to execution.`;
+            }
+            return `Step ${stepLabel} acknowledged. Advancing...`;
+        },
+    };
+}
+// ── activate_todo ────────────────────────────────────────────
+export function createActivateTodoTool(registry) {
+    return {
+        name: 'activate_todo',
+        description: 'Activate TODO mode to break down a complex task into ordered steps. After activation, use add_todo_step to add each step, then call complete_flow_step to start execution. The framework will guide you through one step at a time.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task: {
+                    type: 'string',
+                    description: 'A concise description of the overall task to be completed.',
+                },
+            },
+            required: ['task'],
+        },
+        async execute(args) {
+            const task = args.task ?? '';
+            const todoFlow = registry.get('todo');
+            if (!todoFlow) {
+                return 'TODO flow is not registered. Cannot activate.';
+            }
+            // 激活 TODO Flow（带任务上下文），自动停用当前活跃 Flow
+            registry.activate('todo', { task });
+            return `TODO mode activated for task: "${task}". Break down the task into steps using add_todo_step, then call complete_flow_step to start execution.`;
+        },
+    };
+}
+// ── add_todo_step ────────────────────────────────────────────
+export function createAddTodoStepTool(registry) {
+    return {
+        name: 'add_todo_step',
+        description: 'Add a step to the current TODO flow. Only works when TODO mode is active and in the planning phase. Each step should be a concrete, verifiable action.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                description: {
+                    type: 'string',
+                    description: 'A clear, actionable description of this step. Include what constitutes success.',
+                },
+            },
+            required: ['description'],
+        },
+        async execute(args) {
+            const active = registry.getActive();
+            if (!active || active.id !== 'todo') {
+                return 'TODO mode is not active. Use activate_todo first.';
+            }
+            const todoFlow = registry.get('todo');
+            if (!todoFlow) {
+                return 'TODO flow is not registered.';
+            }
+            const snap = todoFlow.getSnapshot();
+            if (snap.currentState !== 'planning') {
+                return 'Cannot add steps — TODO is already in execution phase.';
+            }
+            const description = args.description ?? '';
+            const step = todoFlow.addStep(description);
+            const allSteps = snap.context.steps ?? [];
+            return `Step #${allSteps.length + 1} added: "${step.prompt}". Total: ${allSteps.length + 1} steps. Add more steps or call complete_flow_step to start execution.`;
+        },
+    };
+}
+//# sourceMappingURL=tools.js.map

package/dist/machine/flows/types.d.ts

@@ -0,0 +1,33 @@
+import type { MachineContext, MachineSnapshot, AdvanceResult } from '../types.js';
+import type { MachineRunner } from '../runner.js';
+/**
+ * FlowController — 所有 Flow 的统一接口。
+ *
+ * 每个 Flow 内部包装一个 MachineRunner 做状态管理，
+ * 对外提供 getInjection() 给 Zone 5 上下文注入。
+ */
+export interface FlowController {
+    /** Flow 唯一标识（与 MachineDef.id 一致） */
+    readonly id: string;
+    /** 内部状态机 */
+    readonly runner: MachineRunner;
+    /** 激活 Flow */
+    activate(context?: MachineContext): void;
+    /** 停用 Flow */
+    deactivate(): void;
+    /** 通过事件推进状态机（委托给 runner.advance） */
+    advance(event: string): AdvanceResult;
+    /** 结构化快照（委托给 runner.getSnapshot） */
+    getSnapshot(): MachineSnapshot;
+    /** Zone 5 注入文本（当前步骤的提示词） */
+    getInjection(): string | null;
+    /** 是否已完成 */
+    isComplete(): boolean;
+    /** 向 Flow 添加定义项（仅 definition 阶段有效，非转移操作）。
+     *  TODO 模式加执行步骤，plan 模式加计划章节，spec 模式不需要。 */
+    addItem?(description: string): {
+        id: string;
+        label: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/machine/flows/types.js

@@ -0,0 +1,10 @@
+// ============================================================
+// Flow Types — Flow 层类型定义
+// ============================================================
+//
+// 扩展 machine 层的通用类型，添加 Flow 特有的概念：
+//   - getInjection() — Zone 5 注入文本
+//   - FlowController — 统一的 Flow 接口
+// ============================================================
+export {};
+//# sourceMappingURL=types.js.map

package/dist/machine/index.d.ts

@@ -0,0 +1,8 @@
+export type { MachineContext, GuardResult, StateDef, TransitionDef, MachineDef, MachineStatus, MachineSnapshot, HistoryEntry, AdvanceResult, } from './types.js';
+export { MachineRunner } from './runner.js';
+export { MachineRegistry } from './registry.js';
+export type { FlowController } from './flows/types.js';
+export { TodoFlow } from './flows/todo.js';
+export { BootstrapFlow } from './flows/bootstrap.js';
+export { SpecFlow } from './flows/spec.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/machine/index.js

@@ -0,0 +1,9 @@
+// ============================================================
+// Machine — 桶导出
+// ============================================================
+export { MachineRunner } from './runner.js';
+export { MachineRegistry } from './registry.js';
+export { TodoFlow } from './flows/todo.js';
+export { BootstrapFlow } from './flows/bootstrap.js';
+export { SpecFlow } from './flows/spec.js';
+//# sourceMappingURL=index.js.map

package/dist/machine/registry.d.ts

@@ -0,0 +1,34 @@
+import type { MachineContext } from './types.js';
+import type { FlowController } from './flows/types.js';
+export declare class MachineRegistry {
+    private flows;
+    private activeId;
+    /** 注册 Flow */
+    register(flow: FlowController): void;
+    /** 按 id 获取 Flow */
+    get(id: string): FlowController | undefined;
+    /** 获取当前活跃的 Flow */
+    getActive(): FlowController | undefined;
+    /** 激活指定 Flow（自动停用当前活跃 Flow） */
+    activate(id: string, context?: MachineContext): void;
+    /** 停用当前活跃 Flow */
+    deactivate(): void;
+    /**
+     * 步骤完成回调。
+     *
+     * 调用活跃 Flow 的 advance('flow_complete')。
+     * 如果转移结果 isTerminal，停用该 Flow。
+     *
+     * @deprecated 请使用 onAdvanceSucceeded — flow_complete 工具内部已调用 advance，
+     *   orchestrator loop 只需检查结果后调用 onAdvanceSucceeded 做清理。
+     */
+    onStepComplete(): Promise<void>;
+    /**
+     * 标记一次成功的 advance 的后续处理。
+     *
+     * flow_complete 工具内部已调用 advance()，
+     * 这里只做 post-advance 清理（terminal → deactivate）。
+     */
+    onAdvanceSucceeded(flowId: string, isTerminal: boolean): void;
+}
+//# sourceMappingURL=registry.d.ts.map