@lingxiao-office/sdk 1.0.0

package/dist/core/ProcessSelfProtection.js

@@ -0,0 +1,234 @@
+/**
+ * ProcessSelfProtection — 进程信号安全防护
+ *
+ * 始终启用的底线守卫，不依赖 hardened mode 配置。
+ *
+ * 设计原则（确定性，非关键词黑名单）：
+ *   信号类命令（kill / pkill / killall）必须以**字面数字 PID** 枚举目标。
+ *   任何在运行时解析目标、按模式匹配、或针对进程组的，一律拦截——
+ *   因为这类命令无法静态证明只杀目标，可能误杀全系统进程（"杀光所有"）。
+ *
+ * 这条单一谓词结构性覆盖所有绕过路径，不枚举任何进程发现工具名：
+ *   - pkill / killall（模式匹配选择器，非字面 PID）
+ *   - kill $(...) / 反引号 / $变量 / ${...}（运行时解析）
+ *   - ... | xargs kill / xargs kill ...（从 stdin 运行时喂 PID）
+ *   - find ... -exec kill ... {}（{} 占位符运行时替换）
+ *   - kill -1 / kill -- -PGID / kill -<负数>（进程组 / 杀全部）
+ *   - kill $PPID / kill $$ / /proc/.../ppid（自杀/杀父）
+ *
+ * 放行：
+ *   - kill <字面正数 PID>（agent 可管理任意明确进程，含重启外部 dev server）
+ *   - kill -0（仅探活，无副作用）
+ *   - kill -l（列信号名）/ kill 无目标（无害）
+ *   - 纯只读探查：ps / lsof / pgrep（非信号命令，快速路径放行）
+ *
+ * 例外：protectedPids（主进程 + worker 子进程）即便以字面 PID 命中也拦截——
+ * 这些核心进程有专用停止机制（stop_agent / graceful shutdown）。
+ */
+const protectedPids = new Set();
+// ─── 注册 API ────────────────────────────────────────
+/** 启动时注册主进程 */
+export function registerMainProcess() {
+    protectedPids.add(process.pid);
+}
+/** Worker 子进程启动时注册 */
+export function registerProtectedPid(pid) {
+    if (Number.isInteger(pid) && pid > 0) {
+        protectedPids.add(pid);
+    }
+}
+/** Worker 退出时注销 */
+export function unregisterProtectedPid(pid) {
+    protectedPids.delete(pid);
+}
+/** 获取当前受保护 PID 集合（测试用） */
+export function getProtectedPids() {
+    return protectedPids;
+}
+/** 重置（仅测试用） */
+export function _resetForTest() {
+    protectedPids.clear();
+}
+// ─── 命令检测 ────────────────────────────────────────
+/**
+ * 信号类命令关键词：kill / pkill / killall。
+ * \b 词边界确保 "skill" 等含 kill 子串的词不误匹配；pkill/killall 作为独立词独立捕获
+ * （旧的 /\bkill\b/ 会漏过 pkill/killall，导致广播杀在默认非加固安装下畅行）。
+ */
+const SIGNAL_COMMAND_RE = /\b(killall|pkill|kill)\b/i;
+/** 广播式 / 运行时解析的进程杀灭统一拦截文案（遵循 rejection-must-guide） */
+const BROADCAST_KILL_ERROR = 'ERROR: 禁止广播式或运行时解析的进程杀灭（pkill/killall/kill $(...)/xargs kill/{}/$变量）。' +
+    '这类命令无法静态证明只杀目标进程，可能误杀全系统进程。' +
+    '改用显式数字 PID（如 kill 12345），或用 terminal_control(action=kill, terminal_id=...) 优雅停止你启动的后台终端。';
+/** 进程组 / "杀全部" 惯法文案 */
+const PROCESS_GROUP_ERROR = 'ERROR: 禁止杀死进程组或全部进程（kill -1 / 负 PID / kill -- -PGID）。这会终止大量无关进程。' +
+    '改用显式的单个正数 PID。';
+/**
+ * 检测命令是否试图以不安全方式发送进程信号。
+ * 返回 null 表示安全，返回错误描述字符串表示拦截。
+ *
+ * 此函数始终启用，不受 hardened mode 开关控制。
+ */
+export function validateCommandForProcessKill(command) {
+    // 空命令放行
+    if (!command || !command.trim())
+        return null;
+    const normalized = command.trim();
+    // 不含信号类关键词的命令直接放行（快速路径）
+    if (!SIGNAL_COMMAND_RE.test(normalized))
+        return null;
+    // 拆分 pipeline / 复合命令中的每条子命令
+    const segments = splitCommandSegments(normalized);
+    for (const segment of segments) {
+        const trimmed = segment.trim();
+        if (!SIGNAL_COMMAND_RE.test(trimmed))
+            continue;
+        const result = analyzeSignalSegment(trimmed);
+        if (result)
+            return result;
+    }
+    return null;
+}
+// ─── 内部实现 ────────────────────────────────────────
+/** 拆分复合命令为独立执行段（按 ;、&&、||、| 拆分，保留引号内容） */
+function splitCommandSegments(command) {
+    const segments = [];
+    let current = '';
+    let inSingle = false;
+    let inDouble = false;
+    let escape = false;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (escape) {
+            current += ch;
+            escape = false;
+            continue;
+        }
+        if (ch === '\\') {
+            current += ch;
+            escape = true;
+            continue;
+        }
+        if (ch === "'" && !inDouble) {
+            inSingle = !inSingle;
+            current += ch;
+            continue;
+        }
+        if (ch === '"' && !inSingle) {
+            inDouble = !inDouble;
+            current += ch;
+            continue;
+        }
+        if (!inSingle && !inDouble) {
+            if (ch === ';' || ch === '|' || ch === '&') {
+                if (current.trim())
+                    segments.push(current);
+                current = '';
+                // 跳过连续的 && 或 ||
+                if ((ch === '&' || ch === '|') && command[i + 1] === ch) {
+                    i++;
+                }
+                continue;
+            }
+        }
+        current += ch;
+    }
+    if (current.trim())
+        segments.push(current);
+    return segments;
+}
+/**
+ * 分析单条含信号类命令的段。返回拦截原因或 null（安全）。
+ *
+ * 判定优先级见文件头注释；核心是"目标必须可静态证明为字面正数 PID"。
+ */
+function analyzeSignalSegment(segment) {
+    // ─── 1. pkill / killall：模式匹配选择器，永远非字面 PID ───
+    if (/\b(pkill|killall)\b/i.test(segment)) {
+        return BROADCAST_KILL_ERROR;
+    }
+    // ─── 2. 信号 0 探活（kill -0 ...）：无副作用，放行 ───
+    if (isSignalZero(segment))
+        return null;
+    // ─── 3. 段内含 xargs + kill：从 stdin 运行时喂 PID ───
+    // 进入此处说明段含 kill（SIGNAL_COMMAND_RE 已匹配），故只需再判 xargs
+    if (/\bxargs\b/i.test(segment)) {
+        return BROADCAST_KILL_ERROR;
+    }
+    // ─── 4. kill $PPID / $$ / ${PPID}：杀父/自杀 ───
+    if (/\bkill\b[^;|&]*\$(\$|PPID|\{PPID\}|\{?\$\}?)/.test(segment)) {
+        return 'ERROR: 禁止杀死父进程/自身（kill $PPID / kill $$）。此操作会终止整个系统。';
+    }
+    // ─── 5. 经 /proc 取父 PID 后杀 ───
+    if (/\bkill\b[^;|&]*\/proc\/(self\/)?ppid/i.test(segment)) {
+        return 'ERROR: 禁止通过 /proc 获取父进程 PID 后杀死。';
+    }
+    // ─── 6/7/8. 取 kill 目标区做字面性 / 进程组 / 受保护 PID 判定 ───
+    const targetArea = getKillTargetArea(segment);
+    // 无目标（kill -l / kill 无参数）→ 无害放行
+    if (!targetArea.trim())
+        return null;
+    // ─── 6. 运行时解析：$ / 反引号 / {} 占位符 ───
+    if (targetArea.includes('$') || targetArea.includes('`') || targetArea.includes('{}')) {
+        return BROADCAST_KILL_ERROR;
+    }
+    // ─── 7. 进程组 / 杀全部：负数字面目标（-1 / -PGID）───
+    if (/(^|\s)-\d+/.test(targetArea)) {
+        return PROCESS_GROUP_ERROR;
+    }
+    // ─── 8. 字面 PID 命中受保护集合（leader + worker 核心）───
+    if (protectedPids.size > 0) {
+        for (const pid of extractNumericPids(segment)) {
+            if (protectedPids.has(pid)) {
+                return `ERROR: 禁止杀死受保护进程 (PID ${pid})。该进程为系统核心组件。`;
+            }
+        }
+    }
+    // ─── 9. 字面正数 PID，安全 ───
+    return null;
+}
+/**
+ * 判断 kill 命令是否仅发送信号 0（探活检测，无副作用）
+ */
+function isSignalZero(segment) {
+    // kill -0 / kill -s 0 / kill --signal 0
+    return /\bkill\s+(-0\b|-s\s+0\b|--signal\s+0\b)/.test(segment);
+}
+/**
+ * 取 kill 命令的目标区：去掉 `kill` 关键词与单个前导信号旗标后的部分。
+ *
+ * kill [-SIGNAL] pid1 pid2 ...     → "pid1 pid2 ..."
+ * kill -s SIGNAL pid ...            → "pid ..."
+ * kill --signal SIGNAL pid ...      → "pid ..."
+ * kill -9 -1                        → "-1"          （负数目标 = 进程组）
+ * kill -l                           → ""            （列信号，无目标）
+ *
+ * 信号只能是 kill 的第一个参数，故只剥离一个前导旗标，避免误剥负数目标。
+ */
+function getKillTargetArea(segment) {
+    const killMatch = segment.match(/\bkill\b\s*(.*)/i);
+    if (!killMatch)
+        return '';
+    let args = killMatch[1];
+    // 逐一尝试剥离单个前导信号旗标（互斥，按最具体优先）
+    args = args.replace(/^--signal\s+\S+\s*/i, '');
+    args = args.replace(/^-s\s+\S+\s*/i, '');
+    args = args.replace(/^-[a-zA-Z0-9]+\s*/, '');
+    return args;
+}
+/**
+ * 从 kill 命令目标区提取显式的正数字 PID 参数。
+ */
+function extractNumericPids(segment) {
+    const targetArea = getKillTargetArea(segment);
+    const pids = [];
+    for (const token of targetArea.split(/\s+/)) {
+        if (/^\d+$/.test(token)) {
+            const pid = parseInt(token, 10);
+            if (pid > 0)
+                pids.push(pid);
+        }
+    }
+    return pids;
+}
+//# sourceMappingURL=ProcessSelfProtection.js.map

package/dist/core/ProcessSelfProtection.js.map

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

package/dist/core/ProjectBlueprint.d.ts

@@ -0,0 +1,176 @@
+export type BlueprintSubsystemStatus = 'implement' | 'defer' | 'not_applicable';
+export interface BlueprintSubsystemEntry {
+    /** 稳定标识,作为 create_task.subsystem 的取值。全蓝图内唯一。 */
+    readonly subsystemId: string;
+    /** 必填:LLM 自写的子系统名称(parseBlueprint 对旧快照缺失时用 subsystemId 兜底)。 */
+    readonly name: string;
+    /** 必填:该子系统涵盖范围(给 Leader 建任务时参考)。parseBlueprint 对旧快照缺失兜底为 ''。 */
+    readonly description: string;
+    readonly status: BlueprintSubsystemStatus;
+    /** defer/not_applicable 必填;implement 时可空 */
+    readonly rationale?: string;
+    /** 已登记到该子系统的任务 id 列表(create_task 带 subsystem 时追加) */
+    readonly taskIds: readonly string[];
+    /** LLM 为该子系统指定的实现角色(可选,scaffold/前端有兜底)。 */
+    readonly agentType?: string;
+    /** 该子系统依赖的其它 subsystemId。必须无环,且引用本清单内的 id(normalize 时过滤非法引用)。
+     *  ready 子系统判定据此拓扑(getReadySubsystems)。 */
+    readonly dependsOn?: readonly string[];
+}
+export interface ProjectBlueprint {
+    readonly subsystems: readonly BlueprintSubsystemEntry[];
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly notes?: string;
+}
+export interface BlueprintSubsystemInput {
+    subsystemId: string;
+    name: string;
+    description: string;
+    status?: BlueprintSubsystemStatus;
+    rationale?: string;
+    agentType?: string;
+    dependsOn?: readonly string[];
+}
+export interface NormalizeBlueprintInput {
+    /** LLM 自写的子系统数组(归一化前的 unknown)。 */
+    subsystems: unknown;
+    notes?: unknown;
+    /** 注入时间戳(测试可控);运行时默认 Date.now() */
+    now?: number;
+    /** 已有蓝图:保留其 taskIds 与 rationale(resume/重定义一致性) */
+    existing?: ProjectBlueprint | null;
+}
+export type NormalizeBlueprintResult = ProjectBlueprint | {
+    error: string;
+};
+/**
+ * 把 LLM 自写的子系统清单归一化为合法蓝图。全确定性、零启发式:
+ *  - subsystems 必须非空;逐条过滤无 id 的;id 必须唯一;name/description 必填。
+ *  - depends_on 引用必须在本清单内,不在的静默过滤(集合判定);整体必须无环(复用 DagScheduler)。
+ *  - defer/not_applicable 必须带 rationale(砍掉一个子系统的实现必须有理由)。
+ *  - 向后兼容:existing 的 taskIds/rationale 保留(resume 一致性)。
+ */
+export declare function normalizeBlueprint(input: NormalizeBlueprintInput): NormalizeBlueprintResult;
+/** 把 taskId 登记到某 subsystem(幂等)。返回新蓝图(不可变)。子系统不存在则原样返回。 */
+export declare function registerTaskId(blueprint: ProjectBlueprint, subsystemId: string, taskId: string, now?: number): ProjectBlueprint;
+/** 从所有 subsystem 移除某 taskId(删任务时调用,保持一致)。返回新蓝图(幂等)。 */
+export declare function unregisterTaskId(blueprint: ProjectBlueprint, taskId: string, now?: number): ProjectBlueprint;
+export interface BlueprintCoverage {
+    /** status=implement 且已登记任务 */
+    readonly implemented: readonly string[];
+    /** status=implement 但无任何任务 → 必须补(dispatch gate 据此拦截) */
+    readonly uncovered: readonly {
+        readonly id: string;
+        readonly name: string;
+    }[];
+    readonly deferred: readonly string[];
+    readonly notApplicable: readonly string[];
+    /** uncovered 为空才允许自由 dispatch */
+    readonly readyToDispatch: boolean;
+}
+/**
+ * 覆盖状态投影。直接按蓝图条目的 status/taskIds 判定(不再查任何外部表),
+ * 否则自定义 subsystemId 会被静默跳过、dispatch gate 失效。
+ */
+export declare function computeBlueprintCoverage(blueprint: ProjectBlueprint): BlueprintCoverage;
+/**
+ * 蓝图中"可推进"的 implement 子系统:其 dependsOn 子系统都已开始(已登记任务)。
+ * 委托通用 DagScheduler.getReadyNodes;只返回候选 id,不自动派发(dispatch 决策归 Leader)。
+ * 用于上下文提示 Leader 按依赖顺序优先建/派任务,治"执行顺序完整性"。
+ */
+export declare function getReadySubsystems(blueprint: ProjectBlueprint, coverage?: BlueprintCoverage): string[];
+/**
+ * 蓝图是否处于"项目活跃"状态:存在未覆盖的 implement 子系统(还没建任务),
+ * 或有任何未 terminal 的登记任务。用于路由锁定——活跃时 chooseExecutionRoute
+ * 倾向 delegate(优先委派),而非 default_autonomous 让 Leader 退回自己干。
+ * isTaskTerminal 由 caller 提供(查 board 真实任务状态),保持本模块纯函数。
+ */
+export declare function isBlueprintActive(blueprint: ProjectBlueprint, isTaskTerminal: (taskId: string) => boolean): boolean;
+/** 子系统契约状态(由 caller 从黑板 ContractPack 查得,保持本模块纯函数)。 */
+export interface SubsystemContractStatus {
+    /** 该 surface 是否有活跃契约 */
+    hasContract: boolean;
+    /** 契约版本(有契约时) */
+    version?: number;
+    /** 是否有 contract 任务(不管是否完成),用于区分"契约收敛中"和"真缺口" */
+    hasContractTask?: boolean;
+}
+/** 蓝图概览(注入 Leader 每轮动态上下文,确定性投影覆盖状态 + 依赖拓扑 + 可推进子系统 + 契约覆盖)。
+ *  contractStatusBySubsystem: 可选,由 caller 从黑板 ContractPack 查得每个子系统 surface 的契约状态。
+ *  未提供时不渲染契约列(向后兼容)。 */
+export declare function renderBlueprintOverview(blueprint: ProjectBlueprint, coverage?: BlueprintCoverage, contractStatusBySubsystem?: ReadonlyMap<string, SubsystemContractStatus>): string;
+/** define_project_blueprint 返回给 Leader 的建任务脚手架(照着 create_task)。 */
+export declare function renderBlueprintScaffold(blueprint: ProjectBlueprint): string;
+/**
+ * 把蓝图 implement 子系统映射成契约种子(surface=子系统 id),供 leader/architect 收敛子系统契约。
+ * 治 planner→blueprint→contract 断裂:子系统清单(由 LLM 自主规划)经此物化成 contract surface 清单,
+ * 让刚完成的蓝图与契约约束合一。纯函数,leader 决策是否 seed(尊重 dispatch 决策权)。
+ */
+export interface SubsystemContractSeed {
+    readonly surface: string;
+    readonly title: string;
+    readonly content: string;
+}
+export declare function buildSubsystemContractSeeds(blueprint: ProjectBlueprint): SubsystemContractSeed[];
+export declare function serializeBlueprint(blueprint: ProjectBlueprint): string;
+/**
+ * 把 session state 里的蓝图 JSON 解析回 ProjectBlueprint。宽容解析,保证 resume 不崩:
+ *  - 不校验 projectType(字段已移除,旧快照可能带也可能不带)。
+ *  - subsystems 必须是非空数组;旧快照 entry 缺 name → 用 subsystemId 兜底,缺 description → ''。
+ */
+export declare function parseBlueprint(raw: unknown): ProjectBlueprint | null;
+export interface AddSubsystemInput {
+    subsystemId: string;
+    name: string;
+    description: string;
+    status?: BlueprintSubsystemStatus;
+    rationale?: string;
+    agentType?: string;
+    dependsOn?: readonly string[];
+}
+export type AddSubsystemResult = ProjectBlueprint | {
+    error: string;
+};
+/**
+ * 添加单个子系统到蓝图。校验同 normalizeBlueprint：
+ *  - subsystemId 必须唯一（不与现有冲突）
+ *  - name/description 必填
+ *  - defer/not_applicable 必须带 rationale
+ *  - dependsOn 引用必须在蓝图内（包括新增的）
+ *  - 添加后整体必须无环
+ */
+export declare function addSubsystem(blueprint: ProjectBlueprint, input: AddSubsystemInput, now?: number): AddSubsystemResult;
+export interface UpdateSubsystemInput {
+    subsystemId: string;
+    name?: string;
+    description?: string;
+    status?: BlueprintSubsystemStatus;
+    rationale?: string;
+    agentType?: string;
+    dependsOn?: readonly string[];
+}
+export type UpdateSubsystemResult = ProjectBlueprint | {
+    error: string;
+};
+/**
+ * 更新子系统属性。只更新提供的字段，未提供的保持不变。
+ * 校验规则：
+ *  - subsystemId 必须存在
+ *  - 更新后 name/description 不能为空
+ *  - defer/not_applicable 必须带 rationale
+ *  - dependsOn 引用必须在蓝图内
+ *  - 更新后整体必须无环
+ */
+export declare function updateSubsystem(blueprint: ProjectBlueprint, input: UpdateSubsystemInput, now?: number): UpdateSubsystemResult;
+export type DeleteSubsystemResult = ProjectBlueprint | {
+    error: string;
+};
+/**
+ * 删除子系统。校验规则：
+ *  - subsystemId 必须存在
+ *  - 不能有其他子系统依赖它（避免破坏依赖链）
+ *  - 如果有关联任务，给出警告但允许删除（任务的 subsystem 绑定会失效）
+ */
+export declare function deleteSubsystem(blueprint: ProjectBlueprint, subsystemId: string, now?: number): DeleteSubsystemResult;
+//# sourceMappingURL=ProjectBlueprint.d.ts.map

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

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