@aiscene/aiserver 1.8.4 → 1.8.6

package/dist/web/server.js

@@ -2,6 +2,8 @@ import express from 'express';
 import fs from 'fs';
 import path from 'path';
 import axios from 'axios';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
 import { createLogger } from '../core/logger.js';
 import { deviceRepo } from '../storage/repositories/device-repo.js';
 import { taskRepo } from '../storage/repositories/task-repo.js';
@@ -11,8 +13,371 @@ import { getDebugPageHtml } from './debug-page.js';
 import { getConfig } from '../config/index.js';
 import { AutobotsClient } from '../core/autobots-client.js';
 import { taskPollerService } from '../task/poller.js';
+import { captureManager } from '../capture/capture-manager.js';
 import { activateAIServer, isNodeAuthUsable, loadNodeAuth, normalizeNodeAuthServerUrl, } from '../auth/node-auth.js';
 const logger = createLogger('WebServer');
+const execFileAsync = promisify(execFile);
+const CODE_WORKSPACE_IGNORED_NAMES = new Set([
+    '.git',
+    '.hg',
+    '.svn',
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+    '.next',
+    '.nuxt',
+    '.turbo',
+    '.cache',
+    '.idea',
+    '.vscode',
+]);
+const CODE_WORKSPACE_SENSITIVE_NAMES = new Set([
+    '.env',
+    '.env.local',
+    '.env.development',
+    '.env.production',
+    '.npmrc',
+    '.yarnrc',
+    'id_rsa',
+    'id_dsa',
+    'id_ecdsa',
+    'id_ed25519',
+]);
+const MAX_CODE_WORKSPACE_ENTRIES = 500;
+const MAX_CODE_WORKSPACE_FILE_BYTES = 1024 * 1024;
+const MAX_CODE_WORKSPACE_FILE_CHARS = 240000;
+const MAX_CODE_WORKSPACE_SEARCH_RESULTS = 200;
+const MAX_CODE_WORKSPACE_COMMAND_OUTPUT_CHARS = 120000;
+const CODE_WORKSPACE_BLOCKED_COMMANDS = [
+    /\brm\s+-rf\s+\/\b/,
+    /\bsudo\b/,
+    /\bshutdown\b/,
+    /\breboot\b/,
+    /\bmkfs\b/,
+    /\bdiskutil\b/,
+];
+function isPathInside(parent, child) {
+    const relative = path.relative(parent, child);
+    return relative === '' || (!!relative && !relative.startsWith('..') && !path.isAbsolute(relative));
+}
+function isAllowedCodeWorkspaceOrigin(req) {
+    const origin = req.headers.origin;
+    if (!origin || typeof origin !== 'string')
+        return true;
+    try {
+        const hostname = new URL(origin).hostname;
+        return (hostname === 'localhost' ||
+            hostname === '127.0.0.1' ||
+            hostname.endsWith('.localhost') ||
+            hostname === 'opentest.jd.com' ||
+            hostname === 'clawai.jd.com' ||
+            hostname.endsWith('.jd.com'));
+    }
+    catch {
+        return false;
+    }
+}
+function isIgnoredWorkspaceName(name) {
+    return CODE_WORKSPACE_IGNORED_NAMES.has(name);
+}
+function isSensitiveWorkspaceName(name) {
+    const lowerName = name.toLowerCase();
+    return CODE_WORKSPACE_SENSITIVE_NAMES.has(lowerName) || lowerName.endsWith('.pem') || lowerName.endsWith('.key');
+}
+async function resolveWorkspaceRoot(rawPath) {
+    const rootPath = typeof rawPath === 'string' ? rawPath.trim() : '';
+    if (!rootPath) {
+        throw new Error('缺少本地工作目录路径');
+    }
+    if (!path.isAbsolute(rootPath)) {
+        throw new Error('本地工作目录必须是绝对路径');
+    }
+    const resolved = path.resolve(rootPath);
+    const realRoot = await fs.promises.realpath(resolved);
+    const stat = await fs.promises.stat(realRoot);
+    if (!stat.isDirectory()) {
+        throw new Error('本地工作目录不是文件夹');
+    }
+    return realRoot;
+}
+async function resolveWorkspaceTarget(root, rawTarget) {
+    const targetText = typeof rawTarget === 'string' && rawTarget.trim() ? rawTarget.trim() : root;
+    const resolved = path.resolve(path.isAbsolute(targetText) ? targetText : path.join(root, targetText));
+    if (!isPathInside(root, resolved)) {
+        throw new Error('目标路径不在本地工作目录内');
+    }
+    const realTarget = await fs.promises.realpath(resolved);
+    if (!isPathInside(root, realTarget)) {
+        throw new Error('目标路径指向工作目录外部');
+    }
+    return realTarget;
+}
+async function resolveWorkspaceWritableTarget(root, rawTarget) {
+    const targetText = typeof rawTarget === 'string' && rawTarget.trim() ? rawTarget.trim() : '';
+    if (!targetText) {
+        throw new Error('缺少目标文件路径');
+    }
+    const resolved = path.resolve(path.isAbsolute(targetText) ? targetText : path.join(root, targetText));
+    if (!isPathInside(root, resolved)) {
+        throw new Error('目标路径不在本地工作目录内');
+    }
+    const parentDir = await fs.promises.realpath(path.dirname(resolved));
+    if (!isPathInside(root, parentDir)) {
+        throw new Error('目标路径指向工作目录外部');
+    }
+    return resolved;
+}
+function truncateWorkspaceText(text, maxChars = MAX_CODE_WORKSPACE_COMMAND_OUTPUT_CHARS) {
+    if (text.length <= maxChars)
+        return { text, truncated: false };
+    return { text: text.slice(0, maxChars), truncated: true };
+}
+function assertSafeWorkspaceFile(filePath, action) {
+    if (isSensitiveWorkspaceName(path.basename(filePath))) {
+        throw new Error(`敏感文件不允许通过工作区${action}`);
+    }
+}
+function assertSafeWorkspaceCommand(command) {
+    const normalized = command.trim();
+    if (!normalized)
+        throw new Error('缺少要执行的命令');
+    if (CODE_WORKSPACE_BLOCKED_COMMANDS.some((pattern) => pattern.test(normalized))) {
+        throw new Error('该命令风险过高，已被本地 AIServer 拦截');
+    }
+}
+function deriveGitRepoDirName(repoUrl) {
+    const cleanUrl = repoUrl.replace(/[?#].*$/, '').replace(/\/+$/, '');
+    const rawName = cleanUrl.split(/[/:]/).filter(Boolean).pop() || 'repository';
+    const withoutGit = rawName.replace(/\.git$/i, '');
+    return withoutGit.replace(/[^A-Za-z0-9._-]/g, '-').replace(/^-+|-+$/g, '') || `repository-${Date.now()}`;
+}
+function assertSafeGitRepoUrl(repoUrl) {
+    if (!repoUrl) {
+        throw new Error('缺少 Git 仓库地址');
+    }
+    if (repoUrl.includes('\n') || repoUrl.includes('\r') || repoUrl.startsWith('-')) {
+        throw new Error('Git 仓库地址不合法');
+    }
+    const isHttps = /^https:\/\/[^\s]+$/i.test(repoUrl);
+    const isSshUrl = /^ssh:\/\/[^\s]+$/i.test(repoUrl);
+    const isScpLikeSsh = /^[A-Za-z0-9._-]+@[A-Za-z0-9._-]+:[^\s]+$/i.test(repoUrl);
+    if (!isHttps && !isSshUrl && !isScpLikeSsh) {
+        throw new Error('Git 仓库地址仅支持 https 或 ssh');
+    }
+}
+function assertSafeGitRefName(refName, label) {
+    if (!refName)
+        return;
+    if (!/^[A-Za-z0-9._/-]+$/.test(refName) || refName.includes('..') || refName.startsWith('-') || refName.endsWith('/')) {
+        throw new Error(`${label}不合法`);
+    }
+}
+async function resolveWorkspaceCloneTarget(root, rawTargetDir, repoUrl) {
+    const targetText = typeof rawTargetDir === 'string' && rawTargetDir.trim()
+        ? rawTargetDir.trim()
+        : deriveGitRepoDirName(repoUrl);
+    if (targetText.includes('\0')) {
+        throw new Error('目标目录不合法');
+    }
+    const parts = targetText.split(/[\\/]+/).filter(Boolean);
+    if (parts.some((part) => part === '..' || isSensitiveWorkspaceName(part) || isIgnoredWorkspaceName(part))) {
+        throw new Error('目标目录包含不允许的路径片段');
+    }
+    const resolved = path.resolve(path.isAbsolute(targetText) ? targetText : path.join(root, targetText));
+    if (!isPathInside(root, resolved)) {
+        throw new Error('目标目录不在本地工作目录内');
+    }
+    const parentDir = await fs.promises.realpath(path.dirname(resolved));
+    if (!isPathInside(root, parentDir)) {
+        throw new Error('目标目录指向工作目录外部');
+    }
+    const existingEntries = await fs.promises.readdir(resolved).catch((error) => {
+        if (error?.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (existingEntries && existingEntries.length > 0) {
+        throw new Error('目标目录已存在且不为空');
+    }
+    return resolved;
+}
+async function hasVisibleChildren(dirPath) {
+    try {
+        const entries = await fs.promises.readdir(dirPath, { withFileTypes: true });
+        return entries.some((entry) => !isIgnoredWorkspaceName(entry.name) && !isSensitiveWorkspaceName(entry.name));
+    }
+    catch {
+        return false;
+    }
+}
+async function buildWorkspaceNode(entryPath, root, depth) {
+    const stat = await fs.promises.lstat(entryPath);
+    const isDirectory = stat.isDirectory();
+    const node = {
+        name: path.basename(entryPath),
+        path: entryPath,
+        relativePath: path.relative(root, entryPath) || '.',
+        isDirectory,
+        size: stat.size,
+        modifiedAt: stat.mtime.toISOString(),
+        hasChildren: isDirectory ? await hasVisibleChildren(entryPath) : false,
+    };
+    if (isDirectory && depth > 0) {
+        node.children = await listWorkspaceDirectory(root, entryPath, depth - 1);
+    }
+    return node;
+}
+async function listWorkspaceDirectory(root, dirPath, depth = 0) {
+    const entries = await fs.promises.readdir(dirPath, { withFileTypes: true });
+    const visibleEntries = entries
+        .filter((entry) => !isIgnoredWorkspaceName(entry.name) && !isSensitiveWorkspaceName(entry.name))
+        .sort((a, b) => {
+        if (a.isDirectory() !== b.isDirectory())
+            return a.isDirectory() ? -1 : 1;
+        return a.name.localeCompare(b.name, 'zh-Hans-CN');
+    })
+        .slice(0, MAX_CODE_WORKSPACE_ENTRIES);
+    const nodes = await Promise.all(visibleEntries.map((entry) => buildWorkspaceNode(path.join(dirPath, entry.name), root, depth)));
+    return nodes;
+}
+async function searchWorkspaceWithNode(root, searchRoot, query, maxResults) {
+    const results = [];
+    const queue = [searchRoot];
+    const lowerQuery = query.toLowerCase();
+    while (queue.length > 0 && results.length < maxResults) {
+        const current = queue.shift();
+        let entries;
+        try {
+            entries = await fs.promises.readdir(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (results.length >= maxResults)
+                break;
+            if (isIgnoredWorkspaceName(entry.name) || isSensitiveWorkspaceName(entry.name))
+                continue;
+            const entryPath = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                queue.push(entryPath);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            let buffer;
+            try {
+                buffer = await fs.promises.readFile(entryPath);
+            }
+            catch {
+                continue;
+            }
+            if (buffer.length > MAX_CODE_WORKSPACE_FILE_BYTES)
+                continue;
+            const text = buffer.toString('utf8');
+            if (text.includes('\u0000'))
+                continue;
+            const lines = text.split(/\r?\n/);
+            for (let index = 0; index < lines.length && results.length < maxResults; index++) {
+                const line = lines[index];
+                if (!line.toLowerCase().includes(lowerQuery))
+                    continue;
+                results.push({
+                    filePath: entryPath,
+                    relativePath: path.relative(root, entryPath),
+                    lineNumber: index + 1,
+                    line: line.slice(0, 1000),
+                });
+            }
+        }
+    }
+    return results;
+}
+async function searchWorkspace(root, searchRoot, query, maxResults) {
+    if (!query.trim()) {
+        throw new Error('缺少搜索关键词');
+    }
+    try {
+        const { stdout } = await execFileAsync('rg', [
+            '--line-number',
+            '--no-heading',
+            '--color',
+            'never',
+            '--hidden',
+            '--glob',
+            '!.git',
+            '--glob',
+            '!node_modules',
+            '--glob',
+            '!dist',
+            '--glob',
+            '!build',
+            '--',
+            query,
+            searchRoot,
+        ], { cwd: root, timeout: 15000, maxBuffer: 4 * 1024 * 1024 });
+        const results = String(stdout || '')
+            .split('\n')
+            .filter(Boolean)
+            .slice(0, maxResults)
+            .map((line) => {
+            const match = line.match(/^(.*?):(\d+):(.*)$/);
+            if (!match) {
+                return { raw: line };
+            }
+            const filePath = path.resolve(match[1]);
+            return {
+                filePath,
+                relativePath: path.relative(root, filePath),
+                lineNumber: Number(match[2]),
+                line: match[3],
+            };
+        });
+        return { root, searchRoot, query, results, truncated: results.length >= maxResults };
+    }
+    catch (error) {
+        if (error?.code === 1) {
+            return { root, searchRoot, query, results: [], truncated: false };
+        }
+        const fallbackResults = await searchWorkspaceWithNode(root, searchRoot, query, maxResults);
+        return { root, searchRoot, query, results: fallbackResults, truncated: fallbackResults.length >= maxResults };
+    }
+}
+async function getGitStatus(root) {
+    try {
+        const [{ stdout: branchStdout }, { stdout: statusStdout }, { stdout: topLevelStdout }] = await Promise.all([
+            execFileAsync('git', ['branch', '--show-current'], { cwd: root, timeout: 5000, maxBuffer: 1024 * 1024 }),
+            execFileAsync('git', ['status', '--short'], { cwd: root, timeout: 5000, maxBuffer: 1024 * 1024 }),
+            execFileAsync('git', ['rev-parse', '--show-toplevel'], { cwd: root, timeout: 5000, maxBuffer: 1024 * 1024 }),
+        ]);
+        const changedFiles = String(statusStdout || '')
+            .split('\n')
+            .map((line) => line.trimEnd())
+            .filter(Boolean)
+            .slice(0, 200)
+            .map((line) => ({
+            status: line.slice(0, 2).trim() || line.slice(0, 1),
+            path: line.slice(3).trim() || line,
+            raw: line,
+        }));
+        const repositoryRoot = String(topLevelStdout || '').trim() || root;
+        return {
+            repositories: [{
+                    root: repositoryRoot,
+                    relativePath: path.relative(root, repositoryRoot) || '.',
+                    branch: String(branchStdout || '').trim() || 'HEAD',
+                    clean: changedFiles.length === 0,
+                    changedFiles,
+                    changedFileCount: changedFiles.length,
+                    truncated: String(statusStdout || '').split('\n').filter(Boolean).length > changedFiles.length,
+                }],
+        };
+    }
+    catch {
+        return { repositories: [] };
+    }
+}
 function normalizeBackendServerUrl(value, fallbackUrl) {
     if (typeof value !== 'string' || !value.trim()) {
         return fallbackUrl;
@@ -343,6 +708,400 @@ export class WebServer {
                 debugSessions,
             });
         });
+        // ===== Local Code Workspace (read-only) =====
+        const guardCodeWorkspace = (req, res) => {
+            if (isAllowedCodeWorkspaceOrigin(req))
+                return true;
+            res.status(403).json({ success: false, message: '当前来源不允许访问本地代码工作区' });
+            return false;
+        };
+        api.post('/code-workspace/status', async (req, res) => {
+            if (!guardCodeWorkspace(req, res))
+                return;
+            try {
+                const root = await resolveWorkspaceRoot(req.body?.path);
+                res.json({
+                    success: true,
+                    data: {
+                        path: root,
+                        exists: true,
+                        isDirectory: true,
+                        gitStatus: await getGitStatus(root),
+                    },
+                });
+            }
+            catch (error) {
+                res.status(400).json({ success: false, message: error.message });
+            }
+        });
+        api.post('/code-workspace/tree', async (req, res) => {
+            if (!guardCodeWorkspace(req, res))
+                return;
+            try {
+                const root = await resolveWorkspaceRoot(req.body?.path);
+                const dirPath = req.body?.dirPath
+                    ? await resolveWorkspaceTarget(root, req.body?.dirPath)
+                    : root;
+                const stat = await fs.promises.stat(dirPath);
+                if (!stat.isDirectory()) {
+                    res.status(400).json({ success: false, message: '目标路径不是文件夹' });
+                    return;
+                }
+                const depth = Math.max(0, Math.min(Number(req.body?.depth ?? 1), 3));
+                const children = await listWorkspaceDirectory(root, dirPath, depth);
+                res.json({ success: true, data: { root, dirPath, tree: children } });
+            }
+            catch (error) {
+                res.status(400).json({ success: false, message: error.message });
+            }
+        });
+        api.post('/code-workspace/children', async (req, res) => {
+            if (!guardCodeWorkspace(req, res))
+                return;
+            try {
+                const root = await resolveWorkspaceRoot(req.body?.path);
+                const dirPath = await resolveWorkspaceTarget(root, req.body?.dirPath);
+                const stat = await fs.promises.stat(dirPath);
+                if (!stat.isDirectory()) {
+                    res.status(400).json({ success: false, message: '目标路径不是文件夹' });
+                    return;
+                }
+                const children = await listWorkspaceDirectory(root, dirPath, 0);
+                res.json({ success: true, data: { root, dirPath, children } });
+            }
+            catch (error) {
+                res.status(400).json({ success: false, message: error.message });
+            }
+        });
+        api.post('/code-workspace/file', async (req, res) => {
+            if (!guardCodeWorkspace(req, res))
+                return;
+            try {
+                const root = await resolveWorkspaceRoot(req.body?.path);
+                const filePath = await resolveWorkspaceTarget(root, req.body?.filePath);
+                const stat = await fs.promises.stat(filePath);
+                if (!stat.isFile()) {
+                    res.status(400).json({ success: false, message: '目标路径不是文件' });
+                    return;
+                }
+                assertSafeWorkspaceFile(filePath, '预览');
+                const buffer = await fs.promises.readFile(filePath);
+                const sliced = buffer.length > MAX_CODE_WORKSPACE_FILE_BYTES
+                    ? buffer.subarray(0, MAX_CODE_WORKSPACE_FILE_BYTES)
+                    : buffer;
+                const text = sliced.toString('utf8');
+                if (text.includes('\u0000')) {
+                    res.status(400).json({ success: false, message: '二进制文件不支持预览' });
+                    return;
+                }
+                const maxChars = Math.max(1, Math.min(Number(req.body?.maxChars ?? MAX_CODE_WORKSPACE_FILE_CHARS), MAX_CODE_WORKSPACE_FILE_CHARS));
+                const content = text.length > maxChars
+                    ? text.slice(0, maxChars)
+                    : text;
+                res.json({
+                    success: true,
+                    data: {
+                        root,
+                        filePath,
+                        content,
+                        size: buffer.length,
+                        truncated: buffer.length > sliced.length || text.length > content.length,
+                    },
+                });
+            }
+            catch (error) {
+                res.status(400).json({ success: false, message: error.message });
+            }
+        });
+        api.post('/code-workspace/file/write', async (req, res) => {
+            if (!guardCodeWorkspace(req, res))
+                return;
+            try {
+                if (req.body?.approved !== true) {
+                    res.status(403).json({ success: false, message: '写入本地文件前必须由用户确认' });
+                    return;
+                }
+                const root = await resolveWorkspaceRoot(req.body?.path);
+                const filePath = await resolveWorkspaceWritableTarget(root, req.body?.filePath);
+                assertSafeWorkspaceFile(filePath, '写入');
+                const exists = await fs.promises.stat(filePath).then((stat) => stat.isFile()).catch(() => false);
+                const parentInvalid = await fs.promises.stat(path.dirname(filePath))
+                    .then((stat) => !stat.isDirectory())
+                    .catch(() => true);
+                if (!exists && parentInvalid) {
+                    res.status(400).json({ success: false, message: '目标文件父目录不存在' });
+                    return;
+                }
+                const content = typeof req.body?.content === 'string' ? req.body.content : '';
+                await fs.promises.writeFile(filePath, content, 'utf8');
+                res.json({
+                    success: true,
+                    data: {
+                        root,
+                        filePath,
+                        created: !exists,
+                        size: Buffer.byteLength(content, 'utf8'),
+                        updatedAt: new Date().toISOString(),
+                    },
+                });
+            }
+            catch (error) {
+                res.status(400).json({ success: false, message: error.message });
+            }
+        });
+        api.post('/code-workspace/git-status', async (req, res) => {
+            if (!guardCodeWorkspace(req, res))
+                return;
+            try {
+                const root = await resolveWorkspaceRoot(req.body?.path);
+                res.json({ success: true, data: await getGitStatus(root) });
+            }
+            catch (error) {
+                res.status(400).json({ success: false, message: error.message });
+            }
+        });
+        api.post('/code-workspace/git-clone', async (req, res) => {
+            if (!guardCodeWorkspace(req, res))
+                return;
+            try {
+                if (req.body?.approved !== true) {
+                    res.status(403).json({ success: false, message: '克隆代码库前必须由用户确认' });
+                    return;
+                }
+                const root = await resolveWorkspaceRoot(req.body?.path);
+                const repoUrl = typeof req.body?.repoUrl === 'string'
+                    ? req.body.repoUrl.trim()
+                    : typeof req.body?.repo_url === 'string'
+                        ? req.body.repo_url.trim()
+                        : '';
+                assertSafeGitRepoUrl(repoUrl);
+                const branch = typeof req.body?.branch === 'string' ? req.body.branch.trim() : '';
+                assertSafeGitRefName(branch, '分支名称');
+                const depthValue = Number(req.body?.depth);
+                const depth = Number.isInteger(depthValue) && depthValue > 0
+                    ? Math.min(depthValue, 1000)
+                    : undefined;
+                const targetPath = await resolveWorkspaceCloneTarget(root, req.body?.targetDir ?? req.body?.target_dir, repoUrl);
+                const args = ['clone'];
+                if (branch)
+                    args.push('--branch', branch);
+                if (depth)
+                    args.push('--depth', String(depth));
+                args.push(repoUrl, targetPath);
+                const { stdout, stderr } = await execFileAsync('git', args, {
+                    cwd: root,
+                    timeout: 10 * 60 * 1000,
+                    maxBuffer: 8 * 1024 * 1024,
+                });
+                const output = truncateWorkspaceText(`${stdout || ''}${stderr ? `\n${stderr}` : ''}`);
+                res.json({
+                    success: true,
+                    data: {
+                        root,
+                        repoUrl,
+                        targetPath,
+                        relativePath: path.relative(root, targetPath),
+                        branch: branch || null,
+                        depth: depth || null,
+                        stdout,
+                        stderr,
+                        output: output.text,
+                        truncated: output.truncated,
+                        gitStatus: await getGitStatus(targetPath),
+                    },
+                });
+            }
+            catch (error) {
+                const stdout = error?.stdout ? String(error.stdout) : '';
+                const stderr = error?.stderr ? String(error.stderr) : '';
+                const output = truncateWorkspaceText(`${stdout}${stderr ? `\n${stderr}` : ''}`);
+                res.status(400).json({
+                    success: false,
+                    message: error.message,
+                    data: {
+                        exitCode: error?.code,
+                        output: output.text,
+                        truncated: output.truncated,
+                    },
+                });
+            }
+        });
+        api.post('/code-workspace/search', async (req, res) => {
+            if (!guardCodeWorkspace(req, res))
+                return;
+            try {
+                const root = await resolveWorkspaceRoot(req.body?.path);
+                const searchRoot = req.body?.searchPath
+                    ? await resolveWorkspaceTarget(root, req.body?.searchPath)
+                    : root;
+                const stat = await fs.promises.stat(searchRoot);
+                if (!stat.isDirectory()) {
+                    res.status(400).json({ success: false, message: '搜索路径不是文件夹' });
+                    return;
+                }
+                const maxResults = Math.max(1, Math.min(Number(req.body?.maxResults ?? 50), MAX_CODE_WORKSPACE_SEARCH_RESULTS));
+                const query = typeof req.body?.query === 'string' ? req.body.query : '';
+                res.json({ success: true, data: await searchWorkspace(root, searchRoot, query, maxResults) });
+            }
+            catch (error) {
+                res.status(400).json({ success: false, message: error.message });
+            }
+        });
+        api.post('/code-workspace/file/edit', async (req, res) => {
+            if (!guardCodeWorkspace(req, res))
+                return;
+            try {
+                if (req.body?.approved !== true) {
+                    res.status(403).json({ success: false, message: '编辑本地文件前必须由用户确认' });
+                    return;
+                }
+                const root = await resolveWorkspaceRoot(req.body?.path);
+                const filePath = await resolveWorkspaceTarget(root, req.body?.filePath);
+                const stat = await fs.promises.stat(filePath);
+                if (!stat.isFile()) {
+                    res.status(400).json({ success: false, message: '目标路径不是文件' });
+                    return;
+                }
+                assertSafeWorkspaceFile(filePath, '编辑');
+                const oldText = typeof req.body?.oldText === 'string' ? req.body.oldText : '';
+                const newText = typeof req.body?.newText === 'string' ? req.body.newText : '';
+                if (!oldText) {
+                    res.status(400).json({ success: false, message: '缺少要替换的原文' });
+                    return;
+                }
+                const original = await fs.promises.readFile(filePath, 'utf8');
+                const firstIndex = original.indexOf(oldText);
+                if (firstIndex < 0) {
+                    res.status(400).json({ success: false, message: '未找到要替换的原文' });
+                    return;
+                }
+                const secondIndex = original.indexOf(oldText, firstIndex + oldText.length);
+                if (secondIndex >= 0) {
+                    res.status(400).json({ success: false, message: '原文匹配到多处，请提供更精确的片段' });
+                    return;
+                }
+                const nextContent = original.slice(0, firstIndex) + newText + original.slice(firstIndex + oldText.length);
+                await fs.promises.writeFile(filePath, nextContent, 'utf8');
+                res.json({
+                    success: true,
+                    data: {
+                        root,
+                        filePath,
+                        replaced: true,
+                        updatedAt: new Date().toISOString(),
+                    },
+                });
+            }
+            catch (error) {
+                res.status(400).json({ success: false, message: error.message });
+            }
+        });
+        api.post('/code-workspace/git-diff', async (req, res) => {
+            if (!guardCodeWorkspace(req, res))
+                return;
+            try {
+                const root = await resolveWorkspaceRoot(req.body?.path);
+                const args = ['diff'];
+                if (req.body?.staged === true)
+                    args.push('--cached');
+                const filePath = req.body?.filePath
+                    ? await resolveWorkspaceTarget(root, req.body?.filePath)
+                    : '';
+                if (filePath)
+                    args.push('--', filePath);
+                const { stdout } = await execFileAsync('git', args, { cwd: root, timeout: 15000, maxBuffer: 4 * 1024 * 1024 });
+                const output = truncateWorkspaceText(String(stdout || ''));
+                res.json({ success: true, data: { root, filePath: filePath || null, diff: output.text, truncated: output.truncated } });
+            }
+            catch (error) {
+                res.status(400).json({ success: false, message: error.message });
+            }
+        });
+        api.post('/code-workspace/git-branch', async (req, res) => {
+            if (!guardCodeWorkspace(req, res))
+                return;
+            try {
+                const root = await resolveWorkspaceRoot(req.body?.path);
+                const operation = req.body?.operation || 'list';
+                if (operation === 'list') {
+                    const { stdout } = await execFileAsync('git', ['branch', '--list'], { cwd: root, timeout: 5000, maxBuffer: 1024 * 1024 });
+                    res.json({
+                        success: true,
+                        data: {
+                            root,
+                            branches: String(stdout || '').split('\n').map((line) => line.trim()).filter(Boolean),
+                        },
+                    });
+                    return;
+                }
+                if (req.body?.approved !== true) {
+                    res.status(403).json({ success: false, message: 'Git 分支变更前必须由用户确认' });
+                    return;
+                }
+                const branchName = typeof req.body?.name === 'string' ? req.body.name.trim() : '';
+                if (!/^[A-Za-z0-9._/-]+$/.test(branchName) || branchName.includes('..') || branchName.startsWith('-')) {
+                    res.status(400).json({ success: false, message: '分支名称不合法' });
+                    return;
+                }
+                const args = operation === 'create'
+                    ? ['checkout', '-b', branchName]
+                    : operation === 'checkout'
+                        ? ['checkout', branchName]
+                        : null;
+                if (!args) {
+                    res.status(400).json({ success: false, message: '不支持的 Git 分支操作' });
+                    return;
+                }
+                const { stdout, stderr } = await execFileAsync('git', args, { cwd: root, timeout: 15000, maxBuffer: 1024 * 1024 });
+                res.json({ success: true, data: { root, operation, branchName, stdout, stderr } });
+            }
+            catch (error) {
+                res.status(400).json({ success: false, message: error.message });
+            }
+        });
+        api.post('/code-workspace/shell', async (req, res) => {
+            if (!guardCodeWorkspace(req, res))
+                return;
+            try {
+                if (req.body?.approved !== true) {
+                    res.status(403).json({ success: false, message: '执行本地命令前必须由用户确认' });
+                    return;
+                }
+                const root = await resolveWorkspaceRoot(req.body?.path);
+                const command = typeof req.body?.command === 'string' ? req.body.command : '';
+                assertSafeWorkspaceCommand(command);
+                const timeout = Math.max(1000, Math.min(Number(req.body?.timeoutMs ?? 120000), 120000));
+                const { stdout, stderr } = await execFileAsync('/bin/sh', ['-lc', command], {
+                    cwd: root,
+                    timeout,
+                    maxBuffer: 4 * 1024 * 1024,
+                });
+                const output = truncateWorkspaceText(`${stdout || ''}${stderr ? `\n${stderr}` : ''}`);
+                res.json({
+                    success: true,
+                    data: {
+                        root,
+                        command,
+                        output: output.text,
+                        truncated: output.truncated,
+                    },
+                });
+            }
+            catch (error) {
+                const stdout = error?.stdout ? String(error.stdout) : '';
+                const stderr = error?.stderr ? String(error.stderr) : '';
+                const output = truncateWorkspaceText(`${stdout}${stderr ? `\n${stderr}` : ''}`);
+                res.status(400).json({
+                    success: false,
+                    message: error.message,
+                    data: {
+                        exitCode: error?.code,
+                        output: output.text,
+                        truncated: output.truncated,
+                    },
+                });
+            }
+        });
         // ===== Devices =====
         api.get('/devices', (_, res) => {
             res.json(deviceRepo.getAll());
@@ -597,6 +1356,136 @@ export class WebServer {
                 res.json({ success: false, message: error.message });
             }
         });
+        // ===== Knowledge Capture API =====
+        api.post('/capture/start', async (req, res) => {
+            try {
+                const result = await captureManager.startCapture(req.body);
+                res.json({ success: true, data: result });
+            }
+            catch (error) {
+                res.status(500).json({ success: false, message: error.message });
+            }
+        });
+        api.post('/capture/stop', async (req, res) => {
+            try {
+                const { sessionId } = req.body;
+                if (!sessionId) {
+                    res.status(400).json({ success: false, message: 'Missing sessionId' });
+                    return;
+                }
+                const result = await captureManager.stopCapture(sessionId);
+                res.json({ success: true, data: result });
+            }
+            catch (error) {
+                res.status(500).json({ success: false, message: error.message });
+            }
+        });
+        api.get('/capture/status/:sessionId', (req, res) => {
+            try {
+                const result = captureManager.getStatus(req.params.sessionId);
+                res.json({ success: true, data: result });
+            }
+            catch (error) {
+                res.status(404).json({ success: false, message: error.message });
+            }
+        });
+        api.post('/capture/snapshot', async (req, res) => {
+            try {
+                const { sessionId } = req.body;
+                if (!sessionId) {
+                    res.status(400).json({ success: false, message: 'Missing sessionId' });
+                    return;
+                }
+                const result = await captureManager.takeSnapshot(sessionId);
+                res.json({ success: true, data: { id: result.id, title: result.title, url: result.url, contentLength: result.content.length, imageCount: result.images.length } });
+            }
+            catch (error) {
+                res.status(500).json({ success: false, message: error.message });
+            }
+        });
+        api.post('/capture/navigate', async (req, res) => {
+            try {
+                const { sessionId, url } = req.body;
+                if (!sessionId || !url) {
+                    res.status(400).json({ success: false, message: 'Missing sessionId or url' });
+                    return;
+                }
+                const result = await captureManager.navigateAndSnapshot(sessionId, url);
+                res.json({ success: true, data: { id: result.id, title: result.title, url: result.url, contentLength: result.content.length } });
+            }
+            catch (error) {
+                res.status(500).json({ success: false, message: error.message });
+            }
+        });
+        api.get('/capture/list', (_, res) => {
+            const result = captureManager.listSessions();
+            res.json({ success: true, data: result });
+        });
+        api.delete('/capture/:sessionId', (req, res) => {
+            captureManager.deleteSession(req.params.sessionId);
+            res.json({ success: true });
+        });
+        // ===== 截图预览 + 操作 API =====
+        api.get('/capture/screenshot/:sessionId', async (req, res) => {
+            try {
+                const screenshot = await captureManager.getScreenshot(req.params.sessionId);
+                res.json({ success: true, data: { screenshot } });
+            }
+            catch (error) {
+                res.status(404).json({ success: false, message: error.message });
+            }
+        });
+        api.get('/capture/screenshot-cache/:sessionId', (req, res) => {
+            try {
+                const screenshot = captureManager.getCachedScreenshot(req.params.sessionId);
+                res.json({ success: true, data: { screenshot } });
+            }
+            catch (error) {
+                res.status(404).json({ success: false, message: error.message });
+            }
+        });
+        api.post('/capture/click', async (req, res) => {
+            try {
+                const { sessionId, x, y } = req.body;
+                if (!sessionId || x === undefined || y === undefined) {
+                    res.status(400).json({ success: false, message: 'Missing sessionId, x or y' });
+                    return;
+                }
+                const result = await captureManager.clickAt(sessionId, Number(x), Number(y));
+                res.json({ success: true, data: { snapshot: { id: result.snapshot.id, title: result.snapshot.title, url: result.snapshot.url, contentLength: result.snapshot.content.length }, screenshot: result.screenshot } });
+            }
+            catch (error) {
+                res.status(500).json({ success: false, message: error.message });
+            }
+        });
+        api.post('/capture/scroll', async (req, res) => {
+            try {
+                const { sessionId, direction, pixels } = req.body;
+                if (!sessionId || !direction) {
+                    res.status(400).json({ success: false, message: 'Missing sessionId or direction' });
+                    return;
+                }
+                const result = await captureManager.scrollPage(sessionId, direction, Number(pixels) || 400);
+                res.json({ success: true, data: { snapshot: { id: result.snapshot.id, title: result.snapshot.title, url: result.snapshot.url, contentLength: result.snapshot.content.length }, screenshot: result.screenshot } });
+            }
+            catch (error) {
+                res.status(500).json({ success: false, message: error.message });
+            }
+        });
+        api.post('/capture/type', async (req, res) => {
+            try {
+                const { sessionId, selector, text } = req.body;
+                if (!sessionId || !selector || text === undefined) {
+                    res.status(400).json({ success: false, message: 'Missing sessionId, selector or text' });
+                    return;
+                }
+                const result = await captureManager.typeText(sessionId, selector, text);
+                res.json({ success: true, data: { snapshot: { id: result.snapshot.id, title: result.snapshot.title, url: result.snapshot.url, contentLength: result.snapshot.content.length }, screenshot: result.screenshot } });
+            }
+            catch (error) {
+                res.status(500).json({ success: false, message: error.message });
+            }
+        });
         this.app.use('/api', api);
     }
     setupDetailRoutes() {