@lingxiao-office/sdk 1.0.0

package/dist/core/TaintFlowEngine.js

@@ -0,0 +1,200 @@
+/**
+ * TaintFlowEngine — JS/TS 过程内污点传播引擎（确定性，无启发式）。
+ *
+ * 用 TypeScript Compiler API 做真正的过程内 value-flow backward analysis：
+ * 从 sink 调用实参出发，沿局部 def-use（变量声明/赋值）、表达式子节点、
+ * 已知透传函数反向追踪，命中声明的 source（如 req.body）即报告，经声明的
+ * sanitizer 截断。自动产出 taint_path（路径节点摘要），灌进 BughuntFinding.taint_path
+ * （此前 taint_path 全靠 LLM 手填）。
+ *
+ * 设计原则（对齐项目）：
+ *   - 确定性：source/sink/sanitizer/propagator 全部显式声明（来自规则 + taintFacts），
+ *     无关键词猜测、无 confidence 分数、无阈值。
+ *   - 过程内：分析范围限定在单个函数体；跨过程（call graph 传播）作为后续增强。
+ *   - 无外部依赖：只用已装的 typescript 编译器 API（与 AstStructuralEngine 一致），
+ *     跨平台零二进制。
+ */
+import ts from 'typescript';
+import { SEED_TAINT_FACTS } from '../tools/implementations/rules/taintFacts.js';
+const DEFAULT_MAX_PATH_DEPTH = 60;
+/**
+ * 分析单个 JS/TS 源文件的过程内污点。
+ * @returns TaintFinding[]（每个 sink↔source 可达路径一条；确定性）。
+ */
+export function analyzeTaintInSource(fileName, sourceText, options) {
+    if (!isJsTs(options.language))
+        return [];
+    const sourceFile = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, /*setParentNodes*/ true, scriptKind(fileName));
+    const sanitizers = options.sanitizers ?? [...SEED_TAINT_FACTS.sanitizers];
+    const propagators = options.propagators ?? [...SEED_TAINT_FACTS.propagators];
+    const sinkSet = new Set(options.sinks);
+    const findings = [];
+    visitFunctions(sourceFile, (fn) => {
+        for (const call of collectSinkCalls(fn, sinkSet)) {
+            const sinkName = calleeName(call);
+            for (const arg of call.arguments) {
+                const result = backwardReach(arg, fn, options.sources, sanitizers, propagators, options.maxPathDepth ?? DEFAULT_MAX_PATH_DEPTH);
+                if (result) {
+                    findings.push({
+                        rule: options.ruleId,
+                        cwe: options.cwe,
+                        severity: options.severity,
+                        file: fileName,
+                        line: lineOf(sourceFile, call),
+                        column: columnOf(sourceFile, call),
+                        source: result.source,
+                        sink: sinkName,
+                        taint_path: [summarize(call), ...result.path],
+                        language: options.language,
+                    });
+                }
+            }
+        }
+    });
+    return findings;
+}
+function isJsTs(lang) {
+    return lang === 'javascript' || lang === 'typescript';
+}
+function scriptKind(fileName) {
+    if (fileName.endsWith('.tsx'))
+        return ts.ScriptKind.TSX;
+    if (fileName.endsWith('.ts'))
+        return ts.ScriptKind.TS;
+    if (fileName.endsWith('.jsx'))
+        return ts.ScriptKind.JSX;
+    return ts.ScriptKind.JS;
+}
+function visitFunctions(node, cb) {
+    if (isFunctionLike(node))
+        cb(node);
+    ts.forEachChild(node, (child) => visitFunctions(child, cb));
+}
+function isFunctionLike(node) {
+    return (ts.isFunctionDeclaration(node) ||
+        ts.isFunctionExpression(node) ||
+        ts.isArrowFunction(node) ||
+        ts.isMethodDeclaration(node) ||
+        ts.isConstructorDeclaration(node) ||
+        ts.isGetAccessorDeclaration(node) ||
+        ts.isSetAccessorDeclaration(node));
+}
+/** 收集函数体内所有 callee 名在 sinkSet 中的调用。 */
+function collectSinkCalls(fn, sinkSet) {
+    const calls = [];
+    const visit = (n) => {
+        if (ts.isCallExpression(n) && sinkSet.has(calleeName(n)))
+            calls.push(n);
+        ts.forEachChild(n, visit);
+    };
+    ts.forEachChild(fn, visit);
+    return calls;
+}
+function calleeName(call) {
+    const expr = call.expression;
+    if (ts.isIdentifier(expr))
+        return expr.text;
+    if (ts.isPropertyAccessExpression(expr))
+        return expr.name.text;
+    return expr.getText();
+}
+/**
+ * 过程内反向 reachability：从 start 节点出发，沿 def-use / 表达式子节点 / 透传函数
+ * 反向追，命中 source 返回路径；sanitizer 截断；visited 防环。
+ */
+function backwardReach(start, scope, sources, sanitizers, propagators, maxDepth) {
+    const worklist = [{ node: start, path: [] }];
+    const visited = new Set();
+    const sanitizerSet = new Set(sanitizers);
+    const propagatorSet = new Set(propagators);
+    while (worklist.length > 0) {
+        const { node, path } = worklist.pop();
+        if (visited.has(node))
+            continue;
+        visited.add(node);
+        if (path.length > maxDepth)
+            continue;
+        // sanitizer 截断：node 是净化器调用 → 该路径终止（不追其内部）
+        if (ts.isCallExpression(node) && sanitizerSet.has(calleeName(node)))
+            continue;
+        // source 命中：节点文本匹配某声明的 source（精确或成员链前缀）
+        const matched = matchSource(node, sources);
+        if (matched) {
+            return { source: matched, path: [...path, summarize(node)] };
+        }
+        const newPath = [...path, summarize(node)];
+        if (ts.isIdentifier(node)) {
+            // 反向追局部定义：name 的初始化 / 赋值 RHS
+            for (const defValue of findDefinitions(node.text, scope)) {
+                worklist.push({ node: defValue, path: newPath });
+            }
+            continue;
+        }
+        if (ts.isBinaryExpression(node)) {
+            // a + b → 两边都可能带污点
+            worklist.push({ node: node.left, path: newPath });
+            worklist.push({ node: node.right, path: newPath });
+            continue;
+        }
+        if (ts.isTemplateExpression(node)) {
+            // `${a}${b}` → 追各插值表达式（head 是字面量，跳过）
+            for (const span of node.templateSpans) {
+                worklist.push({ node: span.expression, path: newPath });
+            }
+            continue;
+        }
+        if (ts.isCallExpression(node)) {
+            // 透传函数：结果污点 ← 实参污点
+            if (propagatorSet.has(calleeName(node))) {
+                for (const arg of node.arguments)
+                    worklist.push({ node: arg, path: newPath });
+            }
+            // 非 propagator 的调用结果：过程内不知返回值来源 → 保守不追
+            continue;
+        }
+        if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isNonNullExpression(node)) {
+            worklist.push({ node: node.expression, path: newPath });
+            continue;
+        }
+        // 其他节点（字面量、属性访问等）：属性访问已在 matchSource 判过；字面量不追
+    }
+    return null;
+}
+function matchSource(node, sources) {
+    const text = node.getText();
+    for (const src of sources) {
+        // 精确匹配，或成员链前缀（req.query.rev 匹配 req.query；obj[key] 匹配 obj）
+        if (text === src || text.startsWith(src + '.') || text.startsWith(src + '[')) {
+            return src;
+        }
+    }
+    return null;
+}
+/** 在 scope（函数体）内找 name 的所有定义的值（变量初始化 / 赋值 RHS）。 */
+function findDefinitions(name, scope) {
+    const defs = [];
+    const visit = (n) => {
+        if (ts.isVariableDeclaration(n) && ts.isIdentifier(n.name) && n.name.text === name && n.initializer) {
+            defs.push(n.initializer);
+        }
+        if (ts.isBinaryExpression(n) &&
+            n.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+            ts.isIdentifier(n.left) &&
+            n.left.text === name) {
+            defs.push(n.right);
+        }
+        ts.forEachChild(n, visit);
+    };
+    ts.forEachChild(scope, visit);
+    return defs;
+}
+function summarize(node) {
+    return node.getText().replace(/\s+/g, ' ').slice(0, 80);
+}
+function lineOf(sourceFile, node) {
+    return sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1;
+}
+function columnOf(sourceFile, node) {
+    return sourceFile.getLineAndCharacterOfPosition(node.getStart()).character + 1;
+}
+//# sourceMappingURL=TaintFlowEngine.js.map

package/dist/core/TaintFlowEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaintFlowEngine.js","sourceRoot":"","sources":["../../src/core/TaintFlowEngine.ts"],"names":[],"mappings":"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"}

package/dist/core/TaskBoard.d.ts

@@ -0,0 +1,243 @@
+import type { DatabaseManager } from './Database.js';
+import type { EventEmitter } from './EventEmitter.js';
+import type { DAGSnapshot, OrchestrationTaskMetadata, RunExplanation, TaskReadiness } from './OrchestrationTypes.js';
+import type { TaskRecord } from '../types/canonical.js';
+import { type ScoredTask } from './TaskPriorityEngine.js';
+import { type CoreTaskExitReason, type CoreTaskStatus } from './StateSemantics.js';
+export type TaskStatus = CoreTaskStatus;
+export type ExitReason = CoreTaskExitReason;
+export interface TaskScopeConfig {
+    working_directory?: string;
+    write_scope?: string[];
+}
+export interface Task extends Omit<TaskRecord, 'status' | 'exitReason' | 'description' | 'working_directory' | 'write_scope'> {
+    description: string;
+    status: TaskStatus;
+    exitReason?: ExitReason;
+    working_directory: string;
+    write_scope: string[];
+}
+export interface TaskStats {
+    total: number;
+    dispatchableRaw: number;
+    ready: number;
+    blocked: number;
+    running: number;
+    terminal: number;
+    completed: number;
+    failed: number;
+    cancelled: number;
+    timeout: number;
+}
+export interface TaskContractReadiness {
+    ready: boolean;
+    reasons?: string[];
+}
+export type TaskContractReadinessResolver = (task: Task) => TaskContractReadiness;
+/**
+ * 任务看板 - 管理任务生命周期
+ */
+export declare class TaskBoard {
+    private db?;
+    private emitter?;
+    private sessionId;
+    private tasks;
+    private taskCounter;
+    private workspaceRoot;
+    private contractReadinessResolver?;
+    /**
+     * 会话级原始用户任务(防漂移:每个新建任务的 context 自动前置它，
+     * 让 worker prompt 始终携带全局目标，对抗子任务执行时忘记用户原始意图)。
+     */
+    private sessionGoal;
+    /**
+     * 终止态任务在内存 Map 中的保留时长（30 分钟）。
+     * 超出后从 Map 中卸载，DB 中仍有完整记录，需要时可从 DB 重新加载。
+     */
+    private static readonly TERMINAL_TASK_TTL_MS;
+    constructor(sessionId: string, db?: DatabaseManager, emitter?: EventEmitter, workspaceRoot?: string);
+    setContractReadinessResolver(resolver?: TaskContractReadinessResolver): void;
+    /** 设置会话级原始任务(防漂移:新建任务的 context 自动前置)。null 关闭。 */
+    setSessionGoal(goal: string | null): void;
+    private resolveTaskPath;
+    private normalizeTaskScope;
+    private isTerminalStatus;
+    private bumpRunGeneration;
+    private computeDerivedTaskStatus;
+    private isDependencySatisfied;
+    private assertDependenciesExist;
+    private wouldCreateDependencyCycle;
+    /** 任务 ready 判定的领域语义注入(委托 DagScheduler.isNodeReady/getReadyNodes)。
+     *  excludeBlocked: getReadyTasks 排除有外部 blocked_reason 的任务;isTaskReady 不排除(保持各自原有语义)。 */
+    private taskReadyDeps;
+    private getContractReadiness;
+    private persistTask;
+    private emitDAGUpdated;
+    refreshReadiness(): void;
+    private attachDependencyLinks;
+    private reconcileTaskStatus;
+    private propagateDependencyState;
+    private rebuildBlocks;
+    nextTaskId(): string;
+    peekNextTaskIds(count?: number): string[];
+    /**
+     * 创建任务
+     */
+    createTask(id: string, subject: string, description: string, agentType: string, blockedBy?: string[], blocks?: string[], scope?: TaskScopeConfig, context?: string, options?: {
+        origin?: string;
+        goal?: string;
+        taskType?: 'bootstrap' | 'reason' | 'explore' | 'generic';
+        orchestration?: OrchestrationTaskMetadata;
+        preferred_agent_name?: string;
+    }): Task;
+    private normalizeDbTask;
+    private buildReadSnapshot;
+    /**
+     * 获取任务
+     *
+     * 内存命中优先；miss 时若 DB 已挂接，做一次单条懒回填，避免 leader 长跑
+     * 后单进程内存被回收却尚未 reloadFromDB 的窗口期返回 undefined。
+     */
+    getTask(id: string): Task | undefined;
+    updateTask(id: string, updates: Partial<Pick<Task, 'subject' | 'description' | 'context' | 'agent_type' | 'blocked_by' | 'preferred_agent_name' | 'orchestration'>> & {
+        scope?: TaskScopeConfig;
+        working_directory?: string;
+        write_scope?: string[];
+    }): Task;
+    deleteTask(id: string): {
+        deletedTask: Task;
+        affectedTasks: Task[];
+    };
+    /**
+     * 更新任务状态
+     *
+     * 注意：合法 transition 和 exitReason 校验必须走 StateSemantics。
+     * TaskBoard 不再维护自己的状态转换表，避免 Web/TUI/QQ/后端内核出现多套规则。
+     */
+    updateTaskStatus(id: string, status: TaskStatus, exitReason?: ExitReason, result?: string | object): void;
+    /**
+     * 分配任务给 Agent
+     *
+     * dispatchable -> running 的合法性由中心状态合同校验；
+     * assignTask 只负责写入执行者和持久化状态。
+     */
+    assignTask(id: string, agentId: string): Task | undefined;
+    /**
+     * 将任务重新放回可恢复调度状态。
+     * 用于 worker 失活后的自治续跑，不把它伪装成仍有活 worker 的 running。
+     */
+    prepareTaskForRedispatch(id: string, reason?: string): void;
+    blockTask(id: string, reason?: string): void;
+    /**
+     * 完成任务
+     */
+    completeTask(id: string, result: string | object): void;
+    /**
+     * 标记任务失败
+     */
+    failTask(id: string, error: string): void;
+    /**
+     * 重开任务：把一个已终止（非 completed）的任务复活回可调度状态。
+     *
+     * 用于 retry 场景——agent 被 terminate / failed / crashed 后任务被标 terminal，
+     * 用户要求重试时需要让这个任务重新可派发。核心状态合同里 terminal 是死状态
+     * （不可转换），所以这里绕过状态机直接重置，但只对「非 completed 终态」生效，
+     * 避免把已经验收完成的任务误重开。
+     *
+     * @returns 是否成功重开（已是非终态 / completed 终态 / 不存在 → false）
+     */
+    reopenTask(id: string, reason?: string): boolean;
+    /**
+     * 写回 orchestration verdict — 让 OrchestrationRuntime.handleTaskResult 的
+     * reject/repair 分支真生效，并落到 DB（重启后保留 verdict 状态）。
+     */
+    setOrchestrationVerdict(id: string, verdict: import('./OrchestrationTypes.js').OrchestrationVerdict): boolean;
+    /**
+     * 取消任务，并将其从下游依赖中移除，避免误建任务永久阻塞后续工作。
+     */
+    cancelTask(id: string, reason?: string): {
+        task: Task;
+        releasedDependents: string[];
+    } | null;
+    /**
+     * 获取所有任务
+     */
+    getAllTasks(): Task[];
+    /**
+     * 获取可调度任务（包括被阻塞的任务）
+     */
+    getPendingTasks(): Task[];
+    /**
+     * 获取运行中任务
+     */
+    getInProgressTasks(): Task[];
+    /**
+     * 获取已完成任务
+     */
+    getCompletedTasks(): Task[];
+    /**
+     * 获取阻塞中的任务（依赖未完成的 dispatchable 任务）
+     */
+    getBlockedTasks(): Task[];
+    getTaskReadiness(task: Task, tasksById?: Map<string, Task>): TaskReadiness;
+    getBlockedReason(task: Task, tasksById?: Map<string, Task>): string | undefined;
+    getDAGSnapshot(): DAGSnapshot;
+    getRunExplanation(snapshot?: DAGSnapshot): RunExplanation;
+    /**
+     * 获取任务统计
+     *
+     * 统计使用 normalizeTaskStatus，保证 DB 快照、内存 Task、Web/TUI 投影看到同一套 completed/failed/cancelled 口径。
+     */
+    getStats(): TaskStats;
+    /**
+     * 检查任务是否可执行（依赖是否完成）
+     */
+    isTaskReady(id: string): boolean;
+    /**
+     * 获取可执行的任务
+     */
+    getReadyTasks(): Task[];
+    /**
+     * 从数据库加载任务
+     */
+    loadFromDB(): Promise<void>;
+    /**
+     * 检查是否所有任务都处于终端状态
+     * 零任务视为"全部终端"（没有非终止态任务）
+     */
+    allTerminal(): boolean;
+    /**
+     * 获取可分发的任务
+     */
+    getDispatchable(): Task[];
+    scoredCandidates(k?: number): ScoredTask[];
+    addDependencies(id: string, dependencyIds: string[]): void;
+    /**
+     * 获取任务摘要文本
+     */
+    getSummaryText(): string;
+    /**
+     * 构造任务看板快照的上下文消息（结构化）。
+     *
+     * 文本内容等同 getSummaryText(),但带 metadata.kind='task_board_snapshot' 判别字段 ——
+     * 上下文压缩器按此字段路由到 task_board 类别压缩器,而非嗅探 "任务统计：" 文本前缀(禁止启发式)。
+     * 需要把任务看板快照塞进会话历史的调用方应使用本方法,而不是直接构造裸文本消息。
+     */
+    getSummaryMessage(): import('../llm/types.js').ChatMessage;
+    /**
+     * 获取失败任务
+     */
+    getFailedTasks(): Task[];
+    /**
+     * 清空任务板
+     */
+    clear(): void;
+    /**
+     * 回收内存中的超龄终止态任务。
+     * 被回收的任务仍存在于 DB 中，下次 getAllTasks() 不影响持久化记录。
+     * 建议由 SessionManager 清理循环或 AgentPool 定期调用。
+     */
+    evictStalledTerminalTasks(): void;
+}
+export default TaskBoard;
+//# sourceMappingURL=TaskBoard.d.ts.map

package/dist/core/TaskBoard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskBoard.d.ts","sourceRoot":"","sources":["../../src/core/TaskBoard.ts"],"names":[],"mappings":"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"}