@hmj-ai/cflow 1.1.0 → 1.3.0

package/dist/src/server.js

@@ -3,22 +3,23 @@ import Fastify from 'fastify';
 import fastifyStatic from '@fastify/static';
 import fastifyMultipart from '@fastify/multipart';
 import { fileURLToPath } from 'node:url';
-import { constants, existsSync, mkdirSync, realpathSync } from 'node:fs';
-import { cp, mkdir, readdir, realpath, rm, stat, access } from 'node:fs/promises';
-import { homedir } from 'node:os';
-import { dirname, isAbsolute, join, sep } from 'node:path';
+import { existsSync, realpathSync } from 'node:fs';
+import { cp, mkdir, rm } from 'node:fs/promises';
+import { dirname, join, sep } from 'node:path';
 import { Store } from './db.js';
-import { compileCF, compileFlow } from './compiler.js';
+import { assertFileReferences, compileCF, compileFlow } from './compiler.js';
 import { Engine, builtins, newRunId } from './engine.js';
 import { RuntimeManager } from './runtime.js';
 import { sha256 } from './hash.js';
-import { requireWorkspaceRoot, validateWorkspaceRoot } from './workspace.js';
+import { initializeWorkspace, validateWorkspaceRoot } from './workspace.js';
+import { missingWorkspaceFiles, searchWorkspaceFiles } from './workspace-files.js';
 import { collectGroundingFailures, groundingError, assertAttachmentGrounding, applyFlowRevision, buildProposalGraph, flowProposalOutputSchema, flowProposalPrompt, matchPublishedCapabilities, prepareSkillAttachments, } from './proposal.js';
 import { flowAgentContext, flowAgentFallback, flowAgentOutputSchema, flowAgentPrompt, normalizeAgentResponse, } from './flow-agent.js';
-export function createApp(store = new Store()) {
+export function createApp(store = new Store(), requestedWorkspaceRoot = process.cwd()) {
+    const workspaceRoot = validateWorkspaceRoot(requestedWorkspaceRoot, 'WORKSPACE_UNAVAILABLE');
     const versions = () => store.list('cf_versions');
     const flowCompilations = () => store.flowCompilations();
-    const runtimes = new RuntimeManager(store);
+    const runtimes = new RuntimeManager(store, { projectRoot: workspaceRoot });
     const testPlans = new Map();
     const testCatalogs = new Map();
     const executorRegistry = builtins();
@@ -27,42 +28,7 @@ export function createApp(store = new Store()) {
         ...versions(),
         ...[...testCatalogs.values()].flat(),
     ]);
-    const storedFlowWorkspace = (flowId) => {
-        const draft = store.get('flow_drafts', flowId);
-        if (draft)
-            return requireWorkspaceRoot(draft.workspaceRoot);
-        const plan = store.list('flow_versions').find((value) => value.flowId === flowId);
-        return plan ? requireWorkspaceRoot(plan.workspaceRoot) : undefined;
-    };
-    const assertFlowWorkspaceImmutable = (draft) => {
-        const requested = requireWorkspaceRoot(draft.workspaceRoot);
-        const stored = storedFlowWorkspace(draft.flowId);
-        if (stored !== undefined && stored !== requested) {
-            try {
-                if (validateWorkspaceRoot(requested) !== stored)
-                    throw new Error('FLOW_WORKSPACE_IMMUTABLE');
-            }
-            catch {
-                throw new Error('FLOW_WORKSPACE_IMMUTABLE');
-            }
-        }
-        return stored ?? requested;
-    };
-    const operationalWorkspace = (draft) => {
-        const requested = assertFlowWorkspaceImmutable(draft);
-        const normalized = validateWorkspaceRoot(requested);
-        if (normalized !== requested)
-            throw new Error('FLOW_WORKSPACE_IMMUTABLE');
-        return normalized;
-    };
-    const normalizeNewFlowWorkspace = (draft) => {
-        const stored = storedFlowWorkspace(draft.flowId);
-        if (stored) {
-            assertFlowWorkspaceImmutable(draft);
-            return draft;
-        }
-        return { ...draft, workspaceRoot: validateWorkspaceRoot(draft.workspaceRoot) };
-    };
+    const scopeFlowDraft = (draft) => ({ ...draft, workspaceRoot });
     const app = Fastify({ logger: true });
     app.register(fastifyMultipart, {
         // Do not silently truncate large skill bundles; files are streamed to disk.
@@ -110,7 +76,7 @@ export function createApp(store = new Store()) {
             nodes: draft.nodes.map((node) => node.kind === 'cf-call' && !node.executor ? { ...node, executor: selected } : node),
         };
     };
-    const saveCompilationSnapshot = (mode, flowDraft, plan, programs, runId) => {
+    const saveCompilationSnapshot = (mode, flowDraft, plan, programs, runId, warnings) => {
         const snapshot = {
             id: `${flowDraft.flowId}@${flowDraft.revision}:${mode}`,
             flowId: flowDraft.flowId,
@@ -119,6 +85,7 @@ export function createApp(store = new Store()) {
             flowDraft,
             plan,
             programs,
+            ...(warnings?.length ? { warnings } : {}),
             runId,
             createdAt: new Date().toISOString(),
         };
@@ -159,7 +126,7 @@ export function createApp(store = new Store()) {
                 await rm(attachments.root, { recursive: true, force: true });
             return proposal;
         }
-        const draft = normalizeNewFlowWorkspace(proposal.flowDraft);
+        const draft = scopeFlowDraft(proposal.flowDraft);
         let archivePath;
         if (attachments) {
             archivePath = join('.cflow', 'flows', draft.flowId, 'attachments');
@@ -180,7 +147,11 @@ export function createApp(store = new Store()) {
                 await rm(attachments.root, { recursive: true, force: true });
             }
         }
-        store.save('flow_drafts', draft.flowId, draft);
+        store.db.transaction(() => {
+            store.save('flow_drafts', draft.flowId, draft);
+            for (const cfDraft of proposal.cfDrafts ?? [])
+                store.save('cf_drafts', cfDraft.cfId, cfDraft);
+        })();
         return {
             ...proposal,
             flowDraft: draft,
@@ -191,49 +162,10 @@ export function createApp(store = new Store()) {
     };
     app.register(fastifyStatic, { root: runtimePublicRoot });
     app.get('/', async (_, reply) => reply.sendFile('index.html'));
+    app.get('/api/workspace', async () => ({ root: workspaceRoot }));
+    app.post('/api/workspace/files/search', async (req) => searchWorkspaceFiles(workspaceRoot, req.body ?? {}));
     app.get('/api/settings', async () => runtimes.settings());
     app.put('/api/settings', async (req) => runtimes.updateSettings(req.body ?? {}));
-    app.get('/api/directories', async (req) => {
-        const requested = req.query.path?.trim() || homedir();
-        if (!isAbsolute(requested))
-            throw new Error('DIRECTORY_PATH_NOT_ABSOLUTE');
-        let path;
-        try {
-            path = await realpath(requested);
-            if (!(await stat(path)).isDirectory())
-                throw new Error('DIRECTORY_NOT_FOUND');
-            await access(path, constants.R_OK);
-        }
-        catch {
-            throw new Error('DIRECTORY_NOT_READABLE');
-        }
-        const children = await readdir(path, { withFileTypes: true });
-        const directories = (await Promise.all(children.map(async (entry) => {
-            const candidate = join(path, entry.name);
-            try {
-                const normalized = await realpath(candidate);
-                if (!(await stat(normalized)).isDirectory())
-                    return null;
-                await access(normalized, constants.R_OK);
-                // Flag dotfiles so the picker can hide developer directories by default.
-                return { name: entry.name, path: normalized, hidden: entry.name.startsWith('.') };
-            }
-            catch {
-                return null;
-            }
-        })))
-            .filter((entry) => Boolean(entry))
-            .sort((a, b) => a.name.localeCompare(b.name));
-        const parentCandidate = dirname(path);
-        return {
-            path,
-            parentPath: parentCandidate === path ? null : await realpath(parentCandidate),
-            directories,
-        };
-    });
-    app.post('/api/directories/validate', async (req) => ({
-        path: validateWorkspaceRoot(req.body?.path, 'DIRECTORY_NOT_READ_WRITE'),
-    }));
     const runtimeCatalog = () => Promise.all(runtimes.profiles().map(async (profile) => ({
         ...profile,
         health: await runtimes.health(profile.id),
@@ -284,13 +216,32 @@ export function createApp(store = new Store()) {
     app.get('/api/flows', async () => store.list('flow_versions'));
     app.get('/api/flow-drafts', async () => store.list('flow_drafts'));
     app.put('/api/flow-drafts/:id', async (req) => {
-        if (req.params.id !== req.body.flowId)
+        const { flowDraft, cfDrafts } = req.body ?? {};
+        if (req.params.id !== flowDraft?.flowId)
             throw new Error('FLOW_DRAFT_ID_MISMATCH');
-        if (!req.body.flowId?.trim() || !req.body.name?.trim() || !req.body.objective?.trim())
+        if (!flowDraft.flowId?.trim() || !flowDraft.name?.trim() || !flowDraft.objective?.trim())
             throw new Error('FLOW_DRAFT_INVALID');
-        const draft = normalizeNewFlowWorkspace(req.body);
-        store.save('flow_drafts', draft.flowId, draft);
-        return draft;
+        if (!Array.isArray(cfDrafts))
+            throw new Error('CF_DRAFTS_REQUIRED');
+        const ids = new Set();
+        for (const cfDraft of cfDrafts) {
+            if (!cfDraft.cfId?.trim() || !Number.isInteger(cfDraft.revision) || cfDraft.revision < 1)
+                throw new Error('CF_DRAFT_INVALID');
+            if (ids.has(cfDraft.cfId))
+                throw new Error('CF_DRAFT_DUPLICATE');
+            ids.add(cfDraft.cfId);
+            assertFileReferences(cfDraft.fileReferences);
+        }
+        const draft = scopeFlowDraft(flowDraft);
+        const stored = store.get('flow_drafts', draft.flowId);
+        if (stored && stored.revision > draft.revision)
+            throw new Error('FLOW_DRAFT_STALE');
+        store.db.transaction(() => {
+            store.save('flow_drafts', draft.flowId, draft);
+            for (const cfDraft of cfDrafts)
+                store.save('cf_drafts', cfDraft.cfId, cfDraft);
+        })();
+        return { flowDraft: draft, cfDrafts };
     });
     app.delete('/api/flow-drafts/:id', async (req, reply) => {
         const result = store.db.prepare('DELETE FROM flow_drafts WHERE id=?').run(req.params.id);
@@ -308,26 +259,58 @@ export function createApp(store = new Store()) {
     app.delete('/api/flows/:id', async (req, reply) => deletePublishedFlow(req.params.id, reply));
     app.delete('/api/flows/:flowId/:flowVersion', async (req, reply) => deletePublishedFlow(`${req.params.flowId}@${req.params.flowVersion}`, reply));
     app.post('/api/flow-compilations', async (req) => {
-        assertFlowWorkspaceImmutable(req.body.flowDraft);
+        const scopedDraft = scopeFlowDraft(req.body.flowDraft);
         const candidates = (req.body.cfDrafts ?? []).map(compileCF);
         const catalog = new Map([...versions(), ...candidates].map((version) => [
             `${version.cfId}@${version.version}`,
             version,
         ]));
-        const selectedDraft = applyCompileRuntime(req.body.flowDraft, req.body.runtimeId);
+        const selectedDraft = applyCompileRuntime(scopedDraft, req.body.runtimeId);
         const compiled = compileFlow(selectedDraft, catalog);
         const plan = req.body.runtimeId
             ? await pinRuntimeProfiles(compiled, [...versions(), ...candidates])
             : compiled;
+        const warnings = [];
+        for (const node of selectedDraft.nodes) {
+            if (node.kind !== 'cf-call')
+                continue;
+            const version = catalog.get(`${node.cfRef.cfId}@${node.cfRef.version}`);
+            const hasFileAccess = (version?.draft.effects ?? []).some((effect) => effect.type === 'file-read' || effect.type === 'file-write');
+            if (!hasFileAccess || !version)
+                continue;
+            const fileReferences = version.draft.fileReferences ?? [];
+            for (const path of await missingWorkspaceFiles(workspaceRoot, fileReferences)) {
+                warnings.push({
+                    code: 'INDEXED_FILE_MISSING',
+                    cfId: version.cfId,
+                    nodeId: node.id,
+                    path,
+                    message: `引用文件不存在：${path}`,
+                });
+            }
+            const indexed = new Set(fileReferences);
+            for (const match of version.draft.does.matchAll(/@\{([^}]+)\}/g)) {
+                const path = match[1];
+                if (!indexed.has(path))
+                    warnings.push({
+                        code: 'FILE_MENTION_NOT_INDEXED',
+                        cfId: version.cfId,
+                        nodeId: node.id,
+                        path,
+                        message: `任务中的文件没有加入引用列表：${path}`,
+                    });
+            }
+        }
         saveCompilationSnapshot('preview', selectedDraft, plan, [...versions(), ...candidates].filter((version) => selectedDraft.nodes.some((node) => node.kind === 'cf-call' &&
             node.cfRef.cfId === version.cfId &&
-            node.cfRef.version === version.version)));
+            node.cfRef.version === version.version)), undefined, warnings);
         const referenced = new Set(selectedDraft.nodes
             .filter((node) => node.kind === 'cf-call')
             .map((node) => `${node.cfRef.cfId}@${node.cfRef.version}`));
         return {
             plan,
             programs: [...catalog.values()].filter((version) => referenced.has(`${version.cfId}@${version.version}`)),
+            warnings,
         };
     });
     app.post('/api/flow-proposals', async (req) => {
@@ -343,7 +326,6 @@ export function createApp(store = new Store()) {
             return new Error(code);
         };
         const body = multipart?.fields ?? req.body;
-        const workspaceRoot = validateWorkspaceRoot(body.workspaceRoot, 'FLOW_WORKSPACE_UNAVAILABLE');
         const objective = String(body.objective ?? '').trim();
         if (!objective)
             throw await failing('OBJECTIVE_REQUIRED');
@@ -455,15 +437,18 @@ export function createApp(store = new Store()) {
         const message = req.body.message?.trim();
         if (!message)
             throw new Error('AGENT_MESSAGE_REQUIRED');
+        const request = {
+            ...req.body,
+            flowDraft: req.body.flowDraft ? scopeFlowDraft(req.body.flowDraft) : null,
+        };
         const catalog = versions();
-        const fallback = flowAgentFallback({ ...req.body, message }, catalog);
-        const runtimeId = req.body.runtimeId?.trim() || runtimes.settings().defaultRuntimeId;
+        const fallback = flowAgentFallback({ ...request, message }, catalog);
+        const runtimeId = request.runtimeId?.trim() || runtimes.settings().defaultRuntimeId;
         const profile = runtimeId ? runtimes.profile(runtimeId) : undefined;
         if (!profile || profile.backend === 'builtin')
             return { ...fallback, fallback: true };
-        if (!req.body.flowDraft)
+        if (!request.flowDraft)
             throw new Error('FLOW_WORKSPACE_REQUIRED');
-        const workspaceRoot = operationalWorkspace(req.body.flowDraft);
         const health = await runtimes.health(runtimeId);
         if (health.status !== 'available')
             return { ...fallback, fallback: true };
@@ -476,13 +461,13 @@ export function createApp(store = new Store()) {
                 availableRuntimes.push({ id: item.id, name: item.name });
         }
         const grounded = Boolean(req.body.attachments?.length);
-        const response = await runtimes.execute(runtimeId, flowAgentPrompt(message, grounded), flowAgentContext({ ...req.body, message }, availableRuntimes, catalog), AbortSignal.timeout(runtimes.settings().testTimeoutMs), [], flowAgentOutputSchema(grounded), { workspaceRoot });
+        const response = await runtimes.execute(runtimeId, flowAgentPrompt(message, grounded), flowAgentContext({ ...request, message }, availableRuntimes, catalog), AbortSignal.timeout(runtimes.settings().testTimeoutMs), [], flowAgentOutputSchema(grounded), { workspaceRoot });
         const normalized = normalizeAgentResponse(response);
         if (normalized.intent === 'answer')
             return { ...normalized, runtimeId };
         if (grounded)
             assertAttachmentGrounding(normalized, req.body.attachments ?? []);
-        const revised = applyFlowRevision(req.body.flowDraft, req.body.cfDrafts ?? [], normalized.stages, { catalog, runtimeId });
+        const revised = applyFlowRevision(request.flowDraft, request.cfDrafts ?? [], normalized.stages, { catalog, runtimeId });
         store.db.transaction(() => {
             for (const draft of revised.cfDrafts)
                 store.save('cf_drafts', draft.cfId, draft);
@@ -516,8 +501,7 @@ export function createApp(store = new Store()) {
         return { deleted: true };
     });
     app.post('/api/flows', async (req) => {
-        const draft = normalizeNewFlowWorkspace(req.body);
-        operationalWorkspace(draft);
+        const draft = scopeFlowDraft(req.body);
         const catalog = versions();
         const plan = await pinRuntimeProfiles(compileFlow(draft, new Map(catalog.map((v) => [`${v.cfId}@${v.version}`, v]))), catalog);
         store.save('flow_drafts', draft.flowId, draft);
@@ -525,14 +509,18 @@ export function createApp(store = new Store()) {
         return plan;
     });
     app.post('/api/flow-tests', async (req) => {
-        operationalWorkspace(req.body.flowDraft);
+        const scopedDraft = scopeFlowDraft(req.body.flowDraft);
         const candidateVersions = (req.body.cfDrafts ?? []).map(compileCF);
         const catalog = new Map([...versions(), ...candidateVersions].map((version) => [
             `${version.cfId}@${version.version}`,
             version,
         ]));
-        const selectedDraft = applyCompileRuntime(req.body.flowDraft, req.body.runtimeId);
-        store.save('flow_drafts', req.body.flowDraft.flowId, req.body.flowDraft);
+        const selectedDraft = applyCompileRuntime(scopedDraft, req.body.runtimeId);
+        store.db.transaction(() => {
+            store.save('flow_drafts', scopedDraft.flowId, scopedDraft);
+            for (const cfDraft of req.body.cfDrafts ?? [])
+                store.save('cf_drafts', cfDraft.cfId, cfDraft);
+        })();
         const compiled = compileFlow(selectedDraft, catalog);
         const plan = await pinRuntimeProfiles(compiled, [...versions(), ...candidateVersions]);
         const programs = [...versions(), ...candidateVersions].filter((version) => selectedDraft.nodes.some((node) => node.kind === 'cf-call' &&
@@ -557,7 +545,8 @@ export function createApp(store = new Store()) {
         const plan = store.get('flow_versions', `${req.body.flowId}@${req.body.flowVersion}`);
         if (!plan)
             throw new Error('FLOW_VERSION_NOT_FOUND');
-        validateWorkspaceRoot(plan.workspaceRoot);
+        if (plan.workspaceRoot !== workspaceRoot)
+            throw new Error('FLOW_WORKSPACE_MISMATCH');
         const resources = resolveResources(plan, req.body.resourceProfileId);
         const id = newRunId();
         store.createRun(id, `${plan.flowId}@${plan.flowVersion}`, req.body.input ?? {}, resources, req.body.resourceProfileId);
@@ -643,10 +632,20 @@ export const isDirectExecution = (entryPath = process.argv[1]) => {
     }
 };
 if (isDirectExecution()) {
-    mkdirSync('./data', { recursive: true });
-    const app = createApp();
-    await app.listen({
-        host: process.env.HOST ?? '127.0.0.1',
-        port: Number(process.env.PORT ?? 3000),
-    });
+    let app;
+    try {
+        const workspace = initializeWorkspace();
+        app = createApp(new Store(workspace.databasePath), workspace.root);
+        app.log.info({ workspace: workspace.root, database: workspace.databasePath }, 'workspace ready');
+        await app.listen({
+            host: process.env.HOST ?? '127.0.0.1',
+            port: Number(process.env.PORT ?? 3000),
+        });
+    }
+    catch (error) {
+        if (app)
+            await app.close();
+        console.error(`CFlow 启动失败：${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    }
 }

package/dist/src/workspace-files.js

@@ -0,0 +1,82 @@
+import { lstat, readdir, realpath } from 'node:fs/promises';
+import { relative, resolve, sep } from 'node:path';
+const EXCLUDED_DIRECTORIES = new Set([
+    '.git',
+    '.cflow',
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+]);
+const RESULT_LIMIT = 200;
+function normalizedRelativePath(value) {
+    const path = value.trim().replaceAll('\\', '/');
+    if (!path || path.startsWith('/') || /^[A-Za-z]:/.test(path))
+        return null;
+    const parts = path.split('/');
+    if (parts.some((part) => !part || part === '.' || part === '..'))
+        return null;
+    if (parts.some((part) => EXCLUDED_DIRECTORIES.has(part)))
+        return null;
+    return path;
+}
+async function isWorkspaceFile(root, path) {
+    const normalized = normalizedRelativePath(path);
+    if (!normalized)
+        return false;
+    const target = resolve(root, ...normalized.split('/'));
+    try {
+        const [stat, resolvedTarget] = await Promise.all([lstat(target), realpath(target)]);
+        const scope = relative(root, resolvedTarget);
+        return (stat.isFile() && scope !== '..' && !scope.startsWith(`..${sep}`) && !scope.startsWith(sep));
+    }
+    catch {
+        return false;
+    }
+}
+async function indexedFiles(root) {
+    const files = [];
+    const walk = async (directory, prefix) => {
+        const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            if (entry.isSymbolicLink())
+                continue;
+            const path = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (!EXCLUDED_DIRECTORIES.has(entry.name))
+                    await walk(resolve(directory, entry.name), path);
+            }
+            else if (entry.isFile()) {
+                files.push(path);
+            }
+        }
+    };
+    await walk(root, '');
+    return files.sort((left, right) => left.localeCompare(right));
+}
+export async function searchWorkspaceFiles(root, input) {
+    const query = String(input.query ?? '')
+        .trim()
+        .toLocaleLowerCase();
+    const safeSelected = [
+        ...new Set((input.selected ?? []).map(normalizedRelativePath).filter(Boolean)),
+    ];
+    const files = await indexedFiles(root);
+    const filtered = query ? files.filter((path) => path.toLocaleLowerCase().includes(query)) : files;
+    const missing = [];
+    for (const path of safeSelected)
+        if (!(await isWorkspaceFile(root, path)))
+            missing.push(path);
+    return {
+        matches: filtered.slice(0, RESULT_LIMIT),
+        missing,
+        truncated: filtered.length > RESULT_LIMIT,
+    };
+}
+export async function missingWorkspaceFiles(root, paths) {
+    const missing = [];
+    for (const path of paths)
+        if (!(await isWorkspaceFile(root, path)))
+            missing.push(path);
+    return missing;
+}

package/dist/src/workspace.js

@@ -1,5 +1,14 @@
-import { accessSync, constants, realpathSync, statSync } from 'node:fs';
-import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync, } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+const gitIgnoreStart = '# cflow:local-data';
+const gitIgnoreEnd = '# /cflow:local-data';
+const managedGitIgnore = `${gitIgnoreStart}
+/cflow.sqlite
+/cflow.sqlite-shm
+/cflow.sqlite-wal
+/cflow.sqlite-journal
+/flows/
+${gitIgnoreEnd}`;
 export function isWithinDirectory(root, candidate) {
     const path = relative(resolve(root), resolve(candidate));
     return path === '' || (path !== '..' && !path.startsWith(`..${sep}`) && !isAbsolute(path));
@@ -24,3 +33,35 @@ export function requireWorkspaceRoot(value) {
         throw new Error('FLOW_WORKSPACE_REQUIRED');
     return value;
 }
+function maintainWorkspaceGitIgnore(dataDirectory) {
+    const file = join(dataDirectory, '.gitignore');
+    const current = existsSync(file) ? readFileSync(file, 'utf8') : '';
+    const start = current.indexOf(gitIgnoreStart);
+    const end = current.indexOf(gitIgnoreEnd);
+    let next;
+    if (start >= 0 && end >= start) {
+        next = `${current.slice(0, start)}${managedGitIgnore}${current.slice(end + gitIgnoreEnd.length)}`;
+    }
+    else {
+        next = `${current.trimEnd()}${current.trim() ? '\n\n' : ''}${managedGitIgnore}\n`;
+    }
+    if (next !== current)
+        writeFileSync(file, next);
+}
+export function initializeWorkspace(value = process.cwd(), environment = process.env) {
+    if (Object.prototype.hasOwnProperty.call(environment, 'CF_DB'))
+        throw new Error('CF_DB_UNSUPPORTED');
+    const root = validateWorkspaceRoot(resolve(value), 'WORKSPACE_UNAVAILABLE');
+    const requestedDataDirectory = join(root, '.cflow');
+    mkdirSync(requestedDataDirectory, { recursive: true });
+    const dataDirectory = realpathSync(requestedDataDirectory);
+    if (!isWithinDirectory(root, dataDirectory))
+        throw new Error('WORKSPACE_DATA_OUTSIDE_ROOT');
+    accessSync(dataDirectory, constants.R_OK | constants.W_OK);
+    maintainWorkspaceGitIgnore(dataDirectory);
+    return {
+        root,
+        dataDirectory,
+        databasePath: join(dataDirectory, 'cflow.sqlite'),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmj-ai/cflow",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "以 Flow 为核心的本机多 Agent 编排工作台",
   "main": "dist/src/server.js",
   "bin": {
@@ -51,6 +51,7 @@
     "@xyflow/react": "^12.11.3",
     "ajv": "^8.20.0",
     "better-sqlite3": "^13.0.3",
+    "cross-spawn": "^7.0.6",
     "fastify": "^5.12.1",
     "lucide-react": "^1.34.0",
     "react": "^19.2.8",