@dsh-plus/agent-preset-rea 0.1.0 → 0.1.2

package/lib/index.js

@@ -1,22 +1,49 @@
-import { unwrapVolatile } from "@dsh-plus/shared";
+import { pluginDataPath, unwrapVolatile } from "@dsh-plus/shared";
 import z from "@deepseek-ai/schemastery";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
 //#region src/mcp.ts
 /** 钉版基线：`rea-agents@6.5.0`（升级时同步测试断言、tests 清单与包文档）。 */
 const REA_PINNED_VERSION = "6.5.0";
-/** stdio 启动命令默认值：POSIX 用 `npx`；Windows 需 `cmd.exe /c npx`（见包文档）。 */
+/** 显式命令配 npx 时的参数配方基准值（`mcpArgs` 留空即按它派生）。 */
 const DEFAULT_MCP_COMMAND = "npx";
 /** REA 工具入参 schema 广告档位：`compact` 压请求前缀体积，`full` 与上游默认一致。 */
 const INPUT_SCHEMA_PROFILES = ["compact", "full"];
 /** REA 工具出参 schema 广告档位：`off` 不下发（结果仍由 REA 侧校验），`full` 与上游默认一致。 */
 const OUTPUT_SCHEMA_PROFILES = ["off", "full"];
-/** stdio 参数：显式配置优先（Windows/全局安装配方），否则按钉版版本派生。 */
+/**
+* 显式命令（`mcpCommand` 非空）时的参数：`mcpArgs` 优先；
+* 留空时 npx 走 `-y rea-agents@<钉版> mcp`，其他可执行文件只补 `mcp`。
+*/
 function reaMcpArgs(config) {
-	return config.mcpArgs.length > 0 ? [...config.mcpArgs] : [
+	if (config.mcpArgs.length > 0) return [...config.mcpArgs];
+	return config.mcpCommand === "npx" ? [
 		"-y",
 		`rea-agents@${config.reaVersion}`,
 		"mcp"
-	];
+	] : ["mcp"];
+}
+/**
+* 本预设 MCP 行的启动方式：
+* 1. `mcpCommand` 显式配置 → 用用户命令（Windows 配方、全局安装场景）；
+* 2. 受管安装存在 → 用当前 node 直接跑安装树里的入口脚本（跨平台、不经 shell shim）；
+* 3. 都没有 → `null`，调用方把该行置 `disabled`（未安装，等卡片上的安装动作）。
+*/
+function reaMcpLaunch(config, installed) {
+	if (config.mcpCommand.trim() !== "") return {
+		command: config.mcpCommand,
+		args: reaMcpArgs(config)
+	};
+	if (installed === null) return null;
+	const extra = config.mcpArgs.length > 0 ? [...config.mcpArgs] : ["mcp"];
+	return {
+		command: installed.command,
+		args: [installed.entry, ...extra]
+	};
 }
 /**
 * 传给 REA 子进程的环境变量（并入被清洗过的宿主环境之上）。
@@ -40,10 +67,11 @@ function reaMcpEnv(config) {
 * 与 settings 用户层（GUI 配置卡片写入 profile 行级覆盖层，loader 原位提交活动
 * 引用，消费端 `unwrapVolatile` 现取即热）。
 *
-* **只有 `personaPrefix` 标 `.volatile()`**：它是对用户的承诺（配置卡片必须给出
-* 编辑器，见 src/client/card.tsx），也是本预设里唯一需要热更的字段；其余字段是
-* **部署方平面**（MCP 参数、超时、附加 skill 根等运维旋钮），由 `cordis.patch.yml`
-* 整体覆盖，GUI 不提供入口。
+* **活动字段（`.volatile()`）共五个**，全部在配置卡片里有编辑器（见 src/client/card.tsx）：
+* `personaPrefix`（提示词）、`proxyPort`（安装代理）、`mcpEnabled` / `skillEnabled` /
+* `reverseSkillEnabled`（三个能力开关）——保存即热更（预设换代，新建会话生效）。
+* 其余字段是**部署方平面**（受管目录、版本钉、skill 组、超时等运维旋钮），由
+* `cordis.patch.yml` 整体覆盖，GUI 不提供入口。
 *
 * **persona 默认为空串**：`dsh-persona` 的空模板照样遮蔽部署级 persona 段，
 * 渲染为空后在提示词里消失；官方装配（harness 身份、工具指引、项目指令、
@@ -61,11 +89,18 @@ const Config = z.object({
 	description: z.string().description("预设说明（设置 → Agent 预设卡片描述）").default("逆向工程预设：官方 standard 全量行 + 仅本预设可见的 REA MCP 客户端（mcp__rea__*）与随包 REA 官方 skill；persona 默认为空，工具指引沿用官方装配。"),
 	order: z.number().description("预设名册排序位").default(6),
 	personaPrefix: z.string().description("persona 前缀（system-prompt 的 deployment:persona-prefix 段）；留空 = 空 persona（该段渲染为空后消失），工具指引与运行时上下文保留").default("").volatile(),
-	mcpEnabled: z.boolean().description("是否挂 REA MCP 客户端行（false = 只保留预设其余能力）").default(true),
+	mcpEnabled: z.boolean().description("是否挂 REA MCP 客户端行（false = 只保留预设其余能力）").default(true).volatile(),
+	skillEnabled: z.boolean().description("是否把 REA 官方 skill 根挂进本预设（false = 模型只看到其余 skill 根）").default(true).volatile(),
+	reverseSkillEnabled: z.boolean().description("是否挂 zhaoxuya520/reverse-skill 技能包（false = 从本预设的 skill 根里摘掉，安装副本仍在）").default(true).volatile(),
+	reverseSkillRepo: z.string().pattern(/^[\w.-]+\/[\w.-]+$/).description("reverse-skill 仓库（<owner>/<repo>；安装/手动更新都从这里拉）").default("zhaoxuya520/reverse-skill"),
+	reverseSkillRef: z.string().description("reverse-skill 的 ref（分支/标签/提交；留空 = 仓库默认分支的最新提交）").default(""),
+	reverseSkillGroups: z.array(z.string()).description("reverse-skill 里挂进本预设的技能组（相对安装树根；默认只挂主包根 skills——含路由技能与全部模块技能，CTF 侧车等组按需追加）").default(["skills"]),
 	mcpServerName: z.string().pattern(/^[A-Za-z0-9_-]{1,32}$/).description("MCP 服务命名空间：模型面工具名为 mcp__<serverName>__<tool>，取值 [A-Za-z0-9_-]{1,32}").default("rea"),
 	reaVersion: z.string().description("钉版的 rea-agents 版本（npx 拉取）").default(REA_PINNED_VERSION),
-	mcpCommand: z.string().description("MCP stdio 可执行文件；Windows 需 cmd.exe 配方，见包文档").default("npx"),
-	mcpArgs: z.array(z.string()).description("MCP stdio 参数；留空 = 按 reaVersion 派生 [\"-y\",\"rea-agents@<version>\",\"mcp\"]").default([]),
+	installRoot: z.string().description("REA 受管安装树位置（空 = <DSH_HOME>/dsh-plus/dsh-plus-agent-preset-rea/rea-agent）").default(""),
+	proxyPort: z.natural().max(65535).description("安装/更新时使用的本机代理端口（0 = 不用代理；npm 与原生依赖 prebuild 下载同此）").default(0).volatile(),
+	mcpCommand: z.string().description("显式 MCP 启动命令（空 = 用受管安装入口，未安装时该行禁用；填 npx 即启动期拉取，风险自负）").default(""),
+	mcpArgs: z.array(z.string()).description("MCP stdio 附加参数；留空 = 受管入口补 [\"mcp\"]，显式 npx 则派生 [\"-y\",\"rea-agents@<version>\",\"mcp\"]").default([]),
 	inputSchemaProfile: z.union(INPUT_SCHEMA_PROFILES).description("REA 工具入参 schema 广告档位（REA_MCP_INPUT_SCHEMA_PROFILE）：compact 压体积，full 与上游默认一致").default("compact"),
 	outputSchemaProfile: z.union(OUTPUT_SCHEMA_PROFILES).description("REA 工具出参 schema 广告档位（REA_MCP_OUTPUT_SCHEMA_PROFILE）：off 不下发（结果仍由 REA 校验），full 与上游默认一致").default("off"),
 	toolCallTimeoutMs: z.number().description("单次 MCP 工具调用超时（毫秒）；REA 分析类调用常超默认 60 秒").default(6e5),
@@ -99,13 +134,401 @@ Make the plan decision-complete: state the goal and success criteria; group impl
 When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
 `;
 //#endregion
+//#region src/exec.ts
+/**
+* 外部命令执行面与作业原语：受管安装/更新作业要跑 `npm` / `tar`，这些调用全部经
+* {@link CommandRunner} 注入，单测用假 runner 跑完整状态机（零网络、零 npm）。
+*
+* 作业阶段由 {@link JobTaskContext} 上报，日志行由 {@link JobOperation} 的调用方
+* 收集；本模块只负责「怎么跑命令」与「怎么把输出变成日志行」。
+* @module @dsh-plus/agent-preset-rea/exec
+*/
+/** 版本字符串形状：进 shell 前把用户可配项收窄成纯版本号。 */
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+/** npm 命令名（Windows 经 shell 执行，见 {@link spawnRunner} 注释）。 */
+const NPM = "npm";
+/** 作业取消（AbortSignal 触发后由 runner 抛出）。 */
+var JobCancelled = class extends Error {
+	constructor() {
+		super("作业已取消");
+		this.name = "JobCancelled";
+	}
+};
+/** 实际 runner：spawn 子进程、逐行回调、AbortSignal 触发即杀。 */
+const spawnRunner = { run: (command, args, options) => new Promise((resolve, reject) => {
+	const child = spawn(command, args, {
+		env: options.env,
+		shell: process.platform === "win32",
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	let pending = "";
+	const emit = (chunk) => {
+		pending += chunk;
+		const lines = pending.split("\n");
+		pending = lines.pop() ?? "";
+		for (const line of lines) options.onLine(line.trimEnd());
+	};
+	child.stdout.setEncoding("utf8");
+	child.stderr.setEncoding("utf8");
+	child.stdout.on("data", emit);
+	child.stderr.on("data", emit);
+	const abort = () => {
+		child.kill("SIGTERM");
+	};
+	options.signal.addEventListener("abort", abort, { once: true });
+	child.on("error", reject);
+	child.on("close", (code) => {
+		options.signal.removeEventListener("abort", abort);
+		if (pending !== "") options.onLine(pending.trimEnd());
+		if (options.signal.aborted) reject(new JobCancelled());
+		else resolve({ code: code ?? 1 });
+	});
+}) };
+/** 本机代理 URL（未配置代理时为 null）。 */
+function proxyUrl(config) {
+	return config.proxyPort > 0 ? `http://127.0.0.1:${config.proxyPort}` : null;
+}
+/**
+* 子进程环境：继承宿主环境，附带代理端口（port > 0 时给 `https_proxy` 系列，
+* prebuild-install 与 curl 都认这些变量——原生依赖 prebuild 下载卡死的正解）。
+* @param config - 插件配置。
+* @param npm - 是否附带 npm 专属开关（npm 子进程用；curl 等非 npm 命令不需要）。
+*/
+function commandEnv(config, npm = false) {
+	const env = {};
+	for (const [key, value] of Object.entries(process.env)) if (value !== void 0) env[key] = value;
+	if (npm) {
+		env["npm_config_audit"] = "false";
+		env["npm_config_fund"] = "false";
+		env["npm_config_update_notifier"] = "false";
+		env["npm_config_loglevel"] = "http";
+	}
+	const proxy = proxyUrl(config);
+	if (proxy !== null) {
+		env["HTTP_PROXY"] = proxy;
+		env["HTTPS_PROXY"] = proxy;
+		env["http_proxy"] = proxy;
+		env["https_proxy"] = proxy;
+		if (npm) {
+			env["npm_config_proxy"] = proxy;
+			env["npm_config_https_proxy"] = proxy;
+		}
+	}
+	return env;
+}
+/** npm 子进程环境（{@link commandEnv} 的 npm 形态）。 */
+function npmEnv(config) {
+	return commandEnv(config, true);
+}
+/** 版本收窄：进命令前把配置里的钉版校验成纯版本号。 */
+function safeVersion(version) {
+	const trimmed = version.trim();
+	if (!VERSION_PATTERN.test(trimmed)) throw new Error(`配置里的 reaVersion 不是合法版本号：${JSON.stringify(version)}`);
+	return trimmed;
+}
+/** 逐行转发子进程输出到作业日志（截断超长行）。 */
+function lineSink(ctx) {
+	return (line) => {
+		if (line !== "") ctx.log(line.slice(0, 500));
+	};
+}
+/** 递归列出目录下全部文件（相对 POSIX 路径，排序稳定）。 */
+function listFiles(dir, base = "") {
+	const out = [];
+	for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+		const rel = base === "" ? entry.name : `${base}/${entry.name}`;
+		if (entry.isDirectory()) out.push(...listFiles(join(dir, entry.name), rel));
+		else out.push(rel);
+	}
+	return out;
+}
+/** 目录下文件数（目录缺席或不可读按 0；状态展示用，不抛）。 */
+function countFiles(dir) {
+	try {
+		return listFiles(dir).length;
+	} catch {
+		return 0;
+	}
+}
+//#endregion
+//#region src/reverse.ts
+/**
+* 第二个受管技能源：GitHub 仓库 `zhaoxuya520/reverse-skill`（路由包：根技能
+* `reverse-skill-router` + 各模块技能目录）。
+*
+* 与 REA 包分开成两个源的理由：来源不同（npm registry vs GitHub 仓库）、版本语义
+* 不同（semver 钉版 vs 提交 sha）、挂载形状不同（单技能根 vs 多技能组），混在一个
+* 作业里会让失败语义含混（npm 成功、GitHub 挂掉时到底算不算成功）。
+*
+* 落点：`<DSH_HOME>/dsh-plus/dsh-plus-agent-preset-rea/reverse-skill/`
+* - `repo/`：仓库树（`tar --strip-components=1` 解开，不改内容）；
+* - `manifest.json`：来源溯源（repo / ref / sha / VERSION / 技能组 / 更新时间）。
+*
+* 技能组发现规则：树里**直接子目录带 `SKILL.md`** 的目录即一个可挂载根（DSH 的
+* skill 扫描正是「根的直接子项 = 技能」）。树根自身不算——它的散装 `.md`
+* （README/AGENTS/RULES 等）会被当成技能文件解析；`plugins/**` 是各客户端的
+* 打包产物（重复一遍路由技能），也不暴露。
+*
+* 作业先落 staging 再换目录：中断只留 staging，运行中的会话继续读旧树。
+* @module @dsh-plus/agent-preset-rea/reverse
+*/
+/** 插件数据目录标识（与 manager.ts 同源：`<DSH_HOME>/dsh-plus/<id>`）。 */
+const PLUGIN_ID$1 = "dsh-plus-agent-preset-rea";
+/** 本技能源在插件数据目录下的子目录名。 */
+const REVERSE_DIR = "reverse-skill";
+/** 仓库树目录名（换目录作业的替换单元是它的父目录）。 */
+const REVERSE_TREE_DIR = "repo";
+/** 默认仓库。 */
+const REVERSE_DEFAULT_REPO = "zhaoxuya520/reverse-skill";
+/** 手动更新作业阶段名。 */
+const REVERSE_PHASES = [
+	"解析仓库信息",
+	"下载源码包",
+	"解包源码",
+	"校验并写入清单"
+];
+/** 不参与技能组发现的目录名（客户端打包产物；会重复一遍路由技能）。 */
+const SKIP_DIRS = /* @__PURE__ */ new Set([
+	".git",
+	"plugins",
+	"node_modules"
+]);
+/** 未安装时的现状（导出给 emptyRuntime 等默认场景用）。 */
+function emptyReverseState(repo = REVERSE_DEFAULT_REPO) {
+	return missingState(repo);
+}
+/** 未安装时的现状。 */
+function missingState(repo) {
+	return {
+		installed: false,
+		repo,
+		ref: null,
+		sha: null,
+		version: null,
+		files: 0,
+		groups: [],
+		updatedAt: null
+	};
+}
+/** 受管路径（固定落插件数据目录，无部署方可调项）。 */
+function reversePaths() {
+	const root = pluginDataPath(PLUGIN_ID$1, REVERSE_DIR);
+	return {
+		root,
+		tree: join(root, REVERSE_TREE_DIR)
+	};
+}
+/** 读 JSON（不存在或坏内容返回 null）。 */
+function readJson$1(file) {
+	try {
+		return JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		return null;
+	}
+}
+/** 记录型守卫。 */
+function asRecord$1(value) {
+	return typeof value === "object" && value !== null ? value : null;
+}
+/** 直接子目录名（跳过不参与发现的目录；目录读不到按无子目录）。 */
+function subdirs(dir) {
+	let entries;
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	return entries.filter((entry) => entry.isDirectory() && !SKIP_DIRS.has(entry.name)).map((entry) => entry.name).sort();
+}
+/** 发现树内的技能组：直接子目录带 SKILL.md 的目录（排除树根与 SKIP_DIRS）。 */
+function discoverSkillGroups(tree) {
+	const groups = [];
+	const walk = (rel) => {
+		const abs = rel === "" ? tree : join(tree, rel);
+		const names = subdirs(abs);
+		if (names.some((name) => existsSync(join(abs, name, "SKILL.md")))) groups.push(rel);
+		for (const name of names) {
+			if (SKIP_DIRS.has(name)) continue;
+			walk(rel === "" ? name : `${rel}/${name}`);
+		}
+	};
+	if (existsSync(tree)) walk("");
+	return groups.filter((rel) => rel !== "");
+}
+/** 现探技能源（清单可读 + 树在 + 至少一个技能组才算可用）。 */
+function probeReverse(config, repo = config.reverseSkillRepo) {
+	const { root, tree } = reversePaths();
+	const manifest = asRecord$1(readJson$1(join(root, "manifest.json")));
+	if (manifest === null || !existsSync(tree)) return missingState(repo);
+	const sha = typeof manifest["sha"] === "string" ? manifest["sha"] : null;
+	if (sha === null) return missingState(repo);
+	const groups = discoverSkillGroups(tree);
+	if (groups.length === 0) return missingState(repo);
+	return {
+		installed: true,
+		repo: typeof manifest["repo"] === "string" ? manifest["repo"] : repo,
+		ref: typeof manifest["ref"] === "string" ? manifest["ref"] : "",
+		sha,
+		version: typeof manifest["version"] === "string" ? manifest["version"] : null,
+		files: typeof manifest["files"] === "number" ? manifest["files"] : countFiles(tree),
+		groups,
+		updatedAt: typeof manifest["updatedAt"] === "string" ? manifest["updatedAt"] : null
+	};
+}
+/**
+* 挂进本预设的技能组目录：配置选中 ∩ 树内发现。
+*
+* 组是否真实存在由现探的 {@link discoverSkillGroups} 负责（发现即存在），这里不再
+* 二次查盘——否则「未安装/组缺席」两种语义会在两处各判一遍。
+* @param config - 插件配置。
+* @param state - 现探现状。
+*/
+function reverseSkillDirs(config, state) {
+	if (!state.installed) return [];
+	const { tree } = reversePaths();
+	return config.reverseSkillGroups.map((group) => group.trim()).filter((group) => group !== "" && state.groups.includes(group)).map((group) => join(tree, group));
+}
+/** curl 通用参数：失败即非零退出、跟随跳转、静默进度。 */
+function curlArgs(config) {
+	const proxy = proxyUrl(config);
+	return ["-fsSL", ...proxy === null ? [] : ["-x", proxy]];
+}
+/** 跑一次 curl 并落文件（失败抛错）。 */
+async function curl(deps, ctx, args, target) {
+	const result = await deps.runner.run("curl", [
+		...curlArgs(deps.config),
+		"-o",
+		target,
+		...args
+	], {
+		env: commandEnv(deps.config),
+		signal: ctx.signal,
+		onLine: lineSink(ctx)
+	});
+	if (result.code !== 0) throw new Error(`curl 失败（退出码 ${result.code}）：${args.join(" ")}`);
+}
+/** GitHub API 取仓库信息（默认分支）与提交 sha。 */
+async function resolveRepo(deps, ctx, staging) {
+	ctx.phase(0);
+	const repo = deps.config.reverseSkillRepo;
+	const api = "https://api.github.com";
+	const metaFile = join(staging, "meta.json");
+	await curl(deps, ctx, [`${api}/repos/${repo}`], metaFile);
+	const meta = asRecord$1(readJson$1(metaFile));
+	const defaultBranch = typeof meta?.["default_branch"] === "string" ? meta["default_branch"] : null;
+	if (defaultBranch === null) throw new Error(`仓库信息不完整（${repo}）`);
+	const ref = deps.config.reverseSkillRef.trim() === "" ? defaultBranch : deps.config.reverseSkillRef.trim();
+	const commitFile = join(staging, "commit.json");
+	await curl(deps, ctx, [`${api}/repos/${repo}/commits/${ref}`], commitFile);
+	const commit = asRecord$1(readJson$1(commitFile));
+	const sha = typeof commit?.["sha"] === "string" ? commit["sha"] : null;
+	if (sha === null) throw new Error(`解析提交失败（${repo}@${ref}）`);
+	ctx.log(`仓库 ${repo}：默认分支 ${defaultBranch}，ref ${ref}，提交 ${sha.slice(0, 12)}`);
+	return {
+		sha,
+		ref
+	};
+}
+/** 下载源码包并解包到 `staging/tree`。 */
+async function fetchTree(deps, ctx, staging) {
+	const { sha } = await resolveRepo(deps, ctx, staging);
+	const tree = join(staging, REVERSE_TREE_DIR);
+	const tarball = join(staging, "repo.tgz");
+	ctx.phase(1);
+	await curl(deps, ctx, [`https://codeload.github.com/${deps.config.reverseSkillRepo}/tar.gz/${sha}`], tarball);
+	ctx.phase(2);
+	await mkdir(tree, { recursive: true });
+	const untar = await deps.runner.run("tar", [
+		"-xzf",
+		tarball,
+		"-C",
+		tree,
+		"--strip-components=1"
+	], {
+		env: commandEnv(deps.config),
+		signal: ctx.signal,
+		onLine: lineSink(ctx)
+	});
+	if (untar.code !== 0) throw new Error(`tar 解包失败（退出码 ${untar.code}）`);
+	return tree;
+}
+/** 读仓库 VERSION（无则 null）。 */
+function readVersion(tree) {
+	try {
+		const text = readFileSync(join(tree, "VERSION"), "utf8").trim();
+		return text === "" ? null : text.split("\n")[0] ?? null;
+	} catch {
+		return null;
+	}
+}
+/** 手动更新作业：拉默认分支/指定 ref 的最新提交，解包后换目录并写清单。 */
+async function runReverseSkillJob(deps, ctx) {
+	const { root } = reversePaths();
+	const staging = `${root}.staging`;
+	await rm(staging, {
+		recursive: true,
+		force: true
+	});
+	await mkdir(staging, { recursive: true });
+	try {
+		const tree = await fetchTree(deps, ctx, staging);
+		ctx.phase(3);
+		const groups = discoverSkillGroups(tree);
+		if (groups.length === 0) throw new Error("仓库结构不含技能组（找不到带 SKILL.md 的子目录）");
+		const meta = asRecord$1(readJson$1(join(staging, "commit.json")));
+		const sha = typeof meta?.["sha"] === "string" ? meta["sha"] : "";
+		for (const scratch of [
+			"repo.tgz",
+			"meta.json",
+			"commit.json"
+		]) await rm(join(staging, scratch), { force: true });
+		const manifest = {
+			source: `github:${deps.config.reverseSkillRepo}@${sha}`,
+			repo: deps.config.reverseSkillRepo,
+			ref: deps.config.reverseSkillRef.trim(),
+			sha,
+			version: readVersion(tree),
+			files: countFiles(tree),
+			groups,
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		await writeFile(join(staging, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+		const backup = `${root}.old`;
+		await rm(backup, {
+			recursive: true,
+			force: true
+		});
+		if (existsSync(root)) await rename(root, backup);
+		await rename(staging, root);
+		await rm(backup, {
+			recursive: true,
+			force: true
+		});
+		deps.refresh();
+		ctx.log(`已更新 ${deps.config.reverseSkillRepo}@${sha.slice(0, 12)}：${manifest.files} 文件、技能组 ${groups.join(", ")}`);
+		return manifest.version ?? sha.slice(0, 12);
+	} catch (error) {
+		await rm(staging, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+}
+//#endregion
 //#region src/skill.ts
 /**
-* 预设作用域内的 skill 根解析：随包 REA 官方 skill + 配置追加目录。
+* 预设作用域内的 skill 根解析：随包 REA 官方 skill（或手动更新副本）+ 配置追加目录。
+*
+* 全部只加在本预设 `skill-filesystem` 行的 `customSkillDirs`（rank 300 的**追加**根）
+* 上，因此不进入项目根 / 用户根 / `$DSH_BUNDLED_SKILL_DIR`，其他预设不受影响。
 *
-* 两者都只加在本预设 `skill-filesystem` 行的 `customSkillDirs`（rank 300 的
-* **追加**根）上，因此不会进入项目根 / 用户根 / `$DSH_BUNDLED_SKILL_DIR`，
-* 其他预设的 skill 目录不受影响。
+* 手动更新副本存在时**替代**随包根而不是并排：两者同名（`reverse-engineer-anything`），
+* 并排只会得到「哪个生效」的歧义。
 * @module @dsh-plus/agent-preset-rea/skill
 */
 /**
@@ -115,9 +538,29 @@ When ready, call exit_plan_mode with the complete plan markdown, starting with a
 * 运行产物两种位置下解析到同一目录。
 */
 const BUNDLED_SKILL_ROOT = fileURLToPath(new URL("../skills", import.meta.url));
-/** skill-filesystem 的追加根清单：随包 REA skill 在前，配置追加目录随后。 */
-function reaSkillDirs(config) {
-	return [BUNDLED_SKILL_ROOT, ...config.extraSkillDirs];
+/**
+* REA skill 根（随包副本，或手动更新副本——后者存在即替代前者）。
+* @param updatedRoot - 手动更新副本根（来自 manager 现探）。
+*/
+function reaSkillDirs(updatedRoot = null) {
+	return updatedRoot === null ? [BUNDLED_SKILL_ROOT] : [updatedRoot];
+}
+/**
+* 本预设 `skill-filesystem` 行的完整追加根清单，按三个开关裁剪：
+* - `skillEnabled=false` → 不挂 REA 官方 skill（安装副本仍留在磁盘）；
+* - `reverseSkillEnabled=false` → 不挂 reverse-skill 的技能组；
+* - `extraSkillDirs` 是部署方追加项，不受开关影响（关掉的是本插件自带的两个源）。
+* @param config - 插件配置。
+* @param runtime - 现探运行期事实。
+*/
+function presetSkillDirs(config, runtime) {
+	const rea = config.skillEnabled === false ? [] : reaSkillDirs(runtime.skill.source === "updated" ? runtime.skill.root : null);
+	const reverse = config.reverseSkillEnabled === false ? [] : reverseSkillDirs(config, runtime.reverse);
+	return [
+		...rea,
+		...reverse,
+		...config.extraSkillDirs
+	];
 }
 //#endregion
 //#region src/definition.ts
@@ -138,198 +581,684 @@ const WINDOWS_ONLY = { __jsExpr: "process.platform === 'win32'" };
 const POSIX_ONLY = { __jsExpr: "process.platform !== 'win32'" };
 /** 官方 loader 的嵌套组行名。 */
 const GROUP = "cordis:group";
+/** 未安装、随包 skill 的运行期事实（默认值：测试与无 manager 场景）。 */
+function emptyRuntime() {
+	return {
+		install: null,
+		skill: {
+			source: "bundled",
+			version: null,
+			root: BUNDLED_SKILL_ROOT,
+			files: 0,
+			updatedAt: null
+		},
+		reverse: emptyReverseState()
+	};
+}
+/**
+* 基础与工具面行：身份（persona）/ 项目指令与时钟 / shell 与文件工具 / 后台任务与
+* 定时提醒 / skill 文件系统（本预设加 `customSkillDirs`，可指向手动更新副本）。
+*/
+function baseRows(config, runtime) {
+	return [
+		{
+			id: "persona",
+			name: "@deepseek-ai/dsh-persona",
+			config: { prefix: config.personaPrefix }
+		},
+		{
+			id: "agent-instructions",
+			name: "@deepseek-ai/dsh-agent-instructions",
+			config: { maxBytes: 65536 }
+		},
+		{
+			id: "time-context",
+			name: "@deepseek-ai/dsh-time-context"
+		},
+		{
+			id: "tool-bash",
+			name: "@deepseek-ai/dsh-tool-bash",
+			disabled: WINDOWS_ONLY
+		},
+		{
+			id: "tool-pwsh",
+			name: "@deepseek-ai/dsh-tool-pwsh",
+			disabled: POSIX_ONLY
+		},
+		{
+			id: "tool-fs",
+			name: "@deepseek-ai/dsh-tool-fs"
+		},
+		{
+			id: "tool-fs-search",
+			name: "@deepseek-ai/dsh-tool-fs-search",
+			config: { sampleOverCapGlobResults: false }
+		},
+		{
+			id: "tool-jobs",
+			name: "@deepseek-ai/dsh-tool-jobs"
+		},
+		{
+			id: "tool-schedule",
+			name: "@deepseek-ai/dsh-tool-schedule"
+		},
+		{
+			id: "skill-filesystem",
+			name: "@deepseek-ai/dsh-skill-filesystem",
+			config: { customSkillDirs: presetSkillDirs(config, runtime) }
+		},
+		{
+			id: "tool-skill",
+			name: "@deepseek-ai/dsh-tool-skill"
+		},
+		{
+			id: "command-goal",
+			name: "@deepseek-ai/dsh-command-goal"
+		},
+		{
+			id: "tool-goal",
+			name: "@deepseek-ai/dsh-tool-goal"
+		}
+	];
+}
+/**
+* 编排与交付面行：计划模式 / 上下文压缩 / 委派与 workflow / 交互与待办 / 网络工具 /
+* **REA MCP 客户端** / 展示与插件管理。
+*/
+function orchestrationRows(config, runtime) {
+	const launch = reaMcpLaunch(config, runtime.install);
+	const mcp = launch ?? {
+		command: "npx",
+		args: reaMcpArgs({
+			...config,
+			mcpCommand: "npx"
+		})
+	};
+	return [
+		{
+			id: "planning",
+			name: GROUP,
+			group: true,
+			isolate: { planMode: true },
+			config: [{
+				id: "plan-mode",
+				name: "@deepseek-ai/dsh-plan-mode",
+				config: { section: PLAN_MODE_SECTION }
+			}]
+		},
+		{
+			id: "compaction",
+			name: GROUP,
+			group: true,
+			isolate: {
+				compaction: true,
+				toolResultPruner: true
+			},
+			config: [
+				{
+					id: "compaction-basic",
+					name: "@deepseek-ai/dsh-compaction-basic"
+				},
+				{
+					id: "command-compact",
+					name: "@deepseek-ai/dsh-command-compact"
+				},
+				{
+					id: "tool-result-pruner",
+					name: "@deepseek-ai/dsh-compaction-tool-result-pruner",
+					config: {
+						thresholdChars: 8192,
+						headChars: 4096,
+						tailChars: 1024
+					}
+				}
+			]
+		},
+		{
+			id: "delegation",
+			name: GROUP,
+			group: true,
+			isolate: { workflowEngine: true },
+			config: [
+				{
+					id: "tool-subagent-control",
+					name: "@deepseek-ai/dsh-tool-subagent-control"
+				},
+				{
+					id: "tool-subagent-list-agents",
+					name: "@deepseek-ai/dsh-tool-subagent-control/list-agents"
+				},
+				{
+					id: "tool-subagent",
+					name: "@deepseek-ai/dsh-tool-subagent",
+					config: {
+						provider: "spawn",
+						toolName: "subagent",
+						modelSelectionSettings: true
+					}
+				},
+				{
+					id: "tool-subagent-fork",
+					name: "@deepseek-ai/dsh-tool-subagent",
+					config: {
+						provider: "fork",
+						toolName: "subagent_fork"
+					}
+				},
+				{
+					id: "workflow-ptc",
+					name: "@deepseek-ai/dsh-workflow-ptc",
+					config: { provider: "spawn" }
+				},
+				{
+					id: "tool-workflow",
+					name: "@deepseek-ai/dsh-tool-workflow"
+				}
+			]
+		},
+		{
+			id: "tool-ask-user",
+			name: "@deepseek-ai/dsh-tool-ask-user"
+		},
+		{
+			id: "tool-todo",
+			name: "@deepseek-ai/dsh-tool-todo",
+			config: { allowParallelInProgress: true }
+		},
+		{
+			id: "tool-web",
+			name: "@deepseek-ai/dsh-tool-web",
+			config: {
+				fetch: true,
+				searchTimeoutMs: 6e4
+			}
+		},
+		{
+			id: "mcp-rea",
+			name: "@deepseek-ai/dsh-mcp-client",
+			disabled: !config.mcpEnabled || launch === null,
+			config: {
+				transport: "stdio",
+				serverName: config.mcpServerName,
+				command: mcp.command,
+				args: mcp.args,
+				env: reaMcpEnv(config),
+				toolCallTimeoutMs: config.toolCallTimeoutMs,
+				failOnStartupError: config.failOnStartupError
+			}
+		},
+		{
+			id: "present",
+			name: "@deepseek-ai/dsh-tool-present"
+		},
+		{
+			id: "tool-plugin-manager",
+			name: "@deepseek-ai/dsh-plugin-manager/tools",
+			disabled: true
+		}
+	];
+}
 /**
-* 由配置拼出注册表声明。
+* 由配置 + 运行期事实拼出注册表声明。
 * @param config - 已验证的插件配置。
+* @param runtime - 受管安装与 skill 来源事实（默认「未安装 + 随包 skill」）。
 * @returns id 固定为 `rea` 的预设声明。
 */
-function reaPresetDefinition(config) {
+function reaPresetDefinition(config, runtime = emptyRuntime()) {
 	return {
 		id: "rea",
 		name: config.name,
 		description: config.description,
 		order: config.order,
-		plugins: [
-			{
-				id: "persona",
-				name: "@deepseek-ai/dsh-persona",
-				config: { prefix: config.personaPrefix }
-			},
-			{
-				id: "agent-instructions",
-				name: "@deepseek-ai/dsh-agent-instructions",
-				config: { maxBytes: 65536 }
-			},
-			{
-				id: "time-context",
-				name: "@deepseek-ai/dsh-time-context"
-			},
-			{
-				id: "tool-bash",
-				name: "@deepseek-ai/dsh-tool-bash",
-				disabled: WINDOWS_ONLY
-			},
-			{
-				id: "tool-pwsh",
-				name: "@deepseek-ai/dsh-tool-pwsh",
-				disabled: POSIX_ONLY
-			},
-			{
-				id: "tool-fs",
-				name: "@deepseek-ai/dsh-tool-fs"
-			},
-			{
-				id: "tool-fs-search",
-				name: "@deepseek-ai/dsh-tool-fs-search",
-				config: { sampleOverCapGlobResults: false }
-			},
-			{
-				id: "tool-jobs",
-				name: "@deepseek-ai/dsh-tool-jobs"
-			},
-			{
-				id: "tool-schedule",
-				name: "@deepseek-ai/dsh-tool-schedule"
-			},
-			{
-				id: "skill-filesystem",
-				name: "@deepseek-ai/dsh-skill-filesystem",
-				config: { customSkillDirs: reaSkillDirs(config) }
-			},
-			{
-				id: "tool-skill",
-				name: "@deepseek-ai/dsh-tool-skill"
-			},
-			{
-				id: "command-goal",
-				name: "@deepseek-ai/dsh-command-goal"
-			},
-			{
-				id: "tool-goal",
-				name: "@deepseek-ai/dsh-tool-goal"
-			},
-			{
-				id: "planning",
-				name: GROUP,
-				group: true,
-				isolate: { planMode: true },
-				config: [{
-					id: "plan-mode",
-					name: "@deepseek-ai/dsh-plan-mode",
-					config: { section: PLAN_MODE_SECTION }
-				}]
-			},
-			{
-				id: "compaction",
-				name: GROUP,
-				group: true,
-				isolate: {
-					compaction: true,
-					toolResultPruner: true
+		plugins: [...baseRows(config, runtime), ...orchestrationRows(config, runtime)]
+	};
+}
+//#endregion
+//#region src/jobs.ts
+/** 阶段序号 → 进度（进入该阶段即报该阶段起点百分比）。 */
+function progressOf(operation, step) {
+	const steps = operation.phases.length;
+	return {
+		step: step + 1,
+		steps,
+		phase: operation.phases[step] ?? "",
+		percent: steps === 0 ? 0 : Math.round(step / steps * 100)
+	};
+}
+/** 落定：写状态 + 通知订阅者（订阅者异常不得影响状态机）。 */
+function settleJob(state, patch) {
+	const base = state.current;
+	if (base === null) return;
+	state.current = {
+		...base,
+		...patch,
+		finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	for (const listener of [...state.listeners]) try {
+		listener(state.current);
+	} catch {}
+}
+/** 兜底进度形状（正常路径下 `state.current` 必有值，这里只防类型上的缺席）。 */
+const ZERO_PROGRESS = {
+	step: 1,
+	steps: 1,
+	phase: "",
+	percent: 0
+};
+/** 收尾：成功记 ok + 版本，失败区分「取消」与「真失败」。 */
+function finishJob(state, error, version) {
+	if (version !== null) {
+		settleJob(state, {
+			state: "ok",
+			version,
+			progress: {
+				...state.current?.progress ?? ZERO_PROGRESS,
+				percent: 100
+			}
+		});
+		return;
+	}
+	const cancelled = error instanceof JobCancelled || state.abort?.signal.aborted === true;
+	settleJob(state, {
+		state: cancelled ? "cancelled" : "error",
+		error: cancelled ? null : error instanceof Error ? error.message : String(error)
+	});
+}
+/** 起一个作业并挂上状态机（调用方已确认当前无运行中作业）。 */
+function startJob(state, kind, operation) {
+	const controller = new AbortController();
+	state.abort = controller;
+	state.seq += 1;
+	const snapshot = {
+		id: state.seq,
+		kind,
+		state: "running",
+		progress: progressOf(operation, 0),
+		log: [],
+		startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		finishedAt: null,
+		version: null,
+		error: null
+	};
+	state.current = snapshot;
+	const push = (patch) => {
+		if (state.current !== null) state.current = {
+			...state.current,
+			...patch
+		};
+	};
+	const ctx = {
+		phase: (step) => push({ progress: progressOf(operation, step) }),
+		log: (line) => push({ log: [...state.current?.log ?? [], line].slice(-200) }),
+		signal: controller.signal
+	};
+	operation.run(ctx).then((version) => finishJob(state, null, version), (error) => finishJob(state, error, null)).finally(() => {
+		state.abort = null;
+	});
+	return snapshot;
+}
+/** 取消当前作业。 */
+function cancelJob(state) {
+	if (state.abort === null || state.current?.state !== "running") return false;
+	state.abort.abort();
+	return true;
+}
+/** 建一个作业板。 */
+function createJobBoard() {
+	const state = {
+		seq: 0,
+		current: null,
+		abort: null,
+		listeners: /* @__PURE__ */ new Set()
+	};
+	return {
+		start: (kind, operation) => state.current?.state === "running" ? null : startJob(state, kind, operation),
+		cancel: () => cancelJob(state),
+		snapshot: () => state.current,
+		onSettled: (listener) => {
+			state.listeners.add(listener);
+			return () => state.listeners.delete(listener);
+		}
+	};
+}
+//#endregion
+//#region src/manager.ts
+/**
+* REA 的受管安装与状态探测：把「REA 包」与「REA skill」都变成插件自己管理的本机资源，
+* 从而摆脱启动期 `npx -y` 拉取（那会在 boot 里跑 npm 安装脚本：原生依赖
+* `@lydell/node-pty` 的 prebuild 下载一旦卡住，预设激活就不返回，名册与插件页
+* 一起被吊住；事故经过见 docs/README.md「启动期拉取的教训」）。
+*
+* 落点（属插件数据，不进 settings，见 @dsh-plus/shared/plugin-data；插件数据目录名
+* 取插件 id `dsh-plus-agent-preset-rea`）：
+* - REA 包：`<DSH_HOME>/dsh-plus/dsh-plus-agent-preset-rea/rea-agent/`（npm --prefix
+*   安装树；入口 `node_modules/rea-agents/scripts/rea.mjs`，用 `process.execPath` 直接
+*   spawn，跨平台不经 shell shim）；
+* - 手动更新的 skill：`<DSH_HOME>/dsh-plus/dsh-plus-agent-preset-rea/skills/`
+*   （根下是 `<技能名>/` + `manifest.json`，与随包 `skills/` 同构；
+*   清单完整时替代随包 skill 根）。
+*
+* 作业都是「先落 staging 再换目录」：中断只留下 staging，不会让半截安装树被当成可用
+* 安装；换目录后清理旧树，运行中的旧进程按 POSIX 语义继续持有已打开文件。
+*
+* 外部进程经 {@link CommandRunner} 注入（见 exec.ts），单测用假 runner 跑完整状态机。
+* @module @dsh-plus/agent-preset-rea/manager
+*/
+/** npm 包名。 */
+const REA_PACKAGE = "rea-agents";
+/** 受管安装树目录名。 */
+const REA_INSTALL_DIR = "rea-agent";
+/** 手动更新 skill 的目录名。 */
+const REA_SKILL_DIR = "skills";
+/** REA 随包 skill 名（tar 包内路径与目录名同此）。 */
+const REA_SKILL_NAME = "reverse-engineer-anything";
+/** 插件数据目录标识（`<DSH_HOME>/dsh-plus/<id>`）。 */
+const PLUGIN_ID = "dsh-plus-agent-preset-rea";
+/** 安装作业阶段名。 */
+const INSTALL_PHASES = [
+	"解析版本信息",
+	`下载并安装 ${REA_PACKAGE}`,
+	"替换安装目录",
+	"校验安装"
+];
+/** skill 作业阶段名。 */
+const SKILL_PHASES = [
+	"解析版本信息",
+	"下载 skill 包",
+	"解包 skills",
+	"校验并写入清单"
+];
+/**
+* 解析受管路径：`installRoot` 非空即运维指定位置（部署方平面），
+* 否则落插件数据目录；skill 更新副本固定落插件数据目录。
+*/
+function managerPaths(config) {
+	const root = config.installRoot.trim();
+	return {
+		installRoot: root === "" ? pluginDataPath(PLUGIN_ID, REA_INSTALL_DIR) : root,
+		skillRoot: pluginDataPath(PLUGIN_ID, REA_SKILL_DIR)
+	};
+}
+/** 读 JSON（不存在或坏内容返回 null）。 */
+function readJson(file) {
+	try {
+		return JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		return null;
+	}
+}
+/** 记录型守卫。 */
+function asRecord(value) {
+	return typeof value === "object" && value !== null ? value : null;
+}
+/** 安装树内固定入口：`node_modules/rea-agents/scripts/rea.mjs`。 */
+function reaEntryFile(root) {
+	return join(root, "node_modules", REA_PACKAGE, "scripts", "rea.mjs");
+}
+/** 从清单 source（`rea-agents@1.2.3`）解析版本。 */
+function versionOfSource(source) {
+	const prefix = `${REA_PACKAGE}@`;
+	return source.startsWith(prefix) ? source.slice(prefix.length) : null;
+}
+/**
+* 探测已安装 REA：包版本可读 **且** 入口脚本存在才算安装完整
+* （只有一半的安装树、或换目录中断留下的 staging 都不算）。
+*/
+function probeInstall(paths) {
+	const pkg = asRecord(readJson(join(paths.installRoot, "node_modules", REA_PACKAGE, "package.json")));
+	const version = typeof pkg?.["version"] === "string" ? pkg["version"] : null;
+	const entry = reaEntryFile(paths.installRoot);
+	if (version === null || !existsSync(entry)) return null;
+	return {
+		version,
+		root: paths.installRoot,
+		command: process.execPath,
+		entry
+	};
+}
+/** 探测 skill 来源：数据目录里清单完整且技能文件在位才认更新副本。 */
+function probeSkill(paths, bundledRoot, bundledVersion) {
+	const manifest = asRecord(readJson(join(paths.skillRoot, "manifest.json")));
+	const source = typeof manifest?.["source"] === "string" ? manifest["source"] : null;
+	const files = Array.isArray(manifest?.["files"]) ? manifest["files"].length : 0;
+	if (source !== null && files > 0 && existsSync(join(paths.skillRoot, "reverse-engineer-anything", "SKILL.md"))) return {
+		source: "updated",
+		version: versionOfSource(source),
+		root: paths.skillRoot,
+		files,
+		updatedAt: typeof manifest?.["updatedAt"] === "string" ? manifest["updatedAt"] : null
+	};
+	return {
+		source: "bundled",
+		version: bundledVersion,
+		root: bundledRoot,
+		files: countFiles(bundledRoot),
+		updatedAt: null
+	};
+}
+/** 现探运行期事实。 */
+function probeRuntime(config, bundledRoot, bundledVersion) {
+	const paths = managerPaths(config);
+	return {
+		install: probeInstall(paths),
+		skill: probeSkill(paths, bundledRoot, bundledVersion),
+		reverse: probeReverse(config)
+	};
+}
+/**
+* 解析钉版在 registry 上的实际版本：顺带做存在性校验（失败即报错，
+* 而不是装出一棵空树让 MCP 行指向不存在的入口）。
+*/
+async function resolveVersion(deps, ctx, wanted) {
+	ctx.phase(0);
+	const lines = [];
+	if ((await deps.runner.run("npm", [
+		"view",
+		`rea-agents@${wanted}`,
+		"version",
+		"--json"
+	], {
+		env: npmEnv(deps.config),
+		signal: ctx.signal,
+		onLine: (line) => {
+			lines.push(line);
+			lineSink(ctx)(line);
+		}
+	})).code !== 0) throw new Error(`registry 上找不到 ${REA_PACKAGE}@${wanted}`);
+	const reported = lines.join("").replace(/["\s]/g, "");
+	if (reported !== "" && reported !== wanted) ctx.log(`registry 返回 ${reported}（配置钉的是 ${wanted}）`);
+}
+/** 装到 staging 并清掉失败现场的公共包壳。 */
+async function npmInstall(deps, ctx, staging) {
+	const version = safeVersion(deps.config.reaVersion);
+	await rm(staging, {
+		recursive: true,
+		force: true
+	});
+	const result = await deps.runner.run("npm", [
+		"install",
+		"--prefix",
+		staging,
+		"--no-audit",
+		"--no-fund",
+		"--loglevel",
+		"http",
+		`${REA_PACKAGE}@${version}`
+	], {
+		env: npmEnv(deps.config),
+		signal: ctx.signal,
+		onLine: lineSink(ctx)
+	});
+	if (result.code !== 0) {
+		await rm(staging, {
+			recursive: true,
+			force: true
+		});
+		throw new Error(`npm install 失败（退出码 ${result.code}）`);
+	}
+}
+/** 安装/更新 REA 包：staging 安装 → 换目录 → 校验入口可读。 */
+async function runInstallJob(deps, ctx) {
+	const version = safeVersion(deps.config.reaVersion);
+	const root = managerPaths(deps.config).installRoot;
+	const staging = `${root}.staging`;
+	await resolveVersion(deps, ctx, version);
+	ctx.phase(1);
+	await npmInstall(deps, ctx, staging);
+	ctx.phase(2);
+	const backup = `${root}.old`;
+	await rm(backup, {
+		recursive: true,
+		force: true
+	});
+	if (existsSync(root)) await rename(root, backup);
+	await rename(staging, root);
+	await rm(backup, {
+		recursive: true,
+		force: true
+	});
+	ctx.phase(3);
+	const probe = probeInstall(managerPaths(deps.config));
+	if (probe === null) throw new Error("安装校验失败：入口脚本不可用");
+	deps.refresh();
+	ctx.log(`已安装 ${REA_PACKAGE}@${probe.version} → ${probe.root}`);
+	return probe.version;
+}
+/** 逐文件 sha256（相对路径 + 字节数）。 */
+function hashFiles(dir) {
+	return listFiles(dir).map((path) => {
+		const bytes = readFileSync(join(dir, path));
+		return {
+			path,
+			sha256: createHash("sha256").update(bytes).digest("hex"),
+			bytes: bytes.length
+		};
+	});
+}
+/** 从 tar 包取钉版 skill 目录（副本根与随包 `skills/` 同构：只 strip 两层）。 */
+async function unpackSkill(deps, ctx, staging, tree) {
+	const version = safeVersion(deps.config.reaVersion);
+	await rm(staging, {
+		recursive: true,
+		force: true
+	});
+	await mkdir(staging, { recursive: true });
+	const packed = await deps.runner.run("npm", [
+		"pack",
+		`${REA_PACKAGE}@${version}`,
+		"--pack-destination",
+		staging,
+		"--loglevel",
+		"http"
+	], {
+		env: npmEnv(deps.config),
+		signal: ctx.signal,
+		onLine: lineSink(ctx)
+	});
+	if (packed.code !== 0) {
+		await rm(staging, {
+			recursive: true,
+			force: true
+		});
+		throw new Error(`npm pack 失败（退出码 ${packed.code}）`);
+	}
+	const tarball = readdirSync(staging).find((name) => name.endsWith(".tgz"));
+	if (tarball === void 0) throw new Error("npm pack 未产出 tarball");
+	ctx.phase(2);
+	await mkdir(tree, { recursive: true });
+	const untar = await deps.runner.run("tar", [
+		"-xzf",
+		join(staging, tarball),
+		"-C",
+		tree,
+		"--strip-components=2",
+		`package/skills/${REA_SKILL_NAME}`
+	], {
+		env: npmEnv(deps.config),
+		signal: ctx.signal,
+		onLine: lineSink(ctx)
+	});
+	if (untar.code !== 0) {
+		await rm(staging, {
+			recursive: true,
+			force: true
+		});
+		throw new Error(`tar 解包失败（退出码 ${untar.code}）`);
+	}
+}
+/** 拉取钉版 tarball 并替换手动更新的 skill 副本（写 sha256 清单后换目录）。 */
+async function runSkillJob(deps, ctx) {
+	const version = safeVersion(deps.config.reaVersion);
+	const root = managerPaths(deps.config).skillRoot;
+	const staging = `${root}.staging`;
+	const tree = join(staging, "tree");
+	await resolveVersion(deps, ctx, version);
+	ctx.phase(1);
+	await unpackSkill(deps, ctx, staging, tree);
+	ctx.phase(3);
+	const files = hashFiles(tree);
+	if (files.length === 0) throw new Error("解包结果为空：上游 skill 目录结构可能已变");
+	const manifest = {
+		source: `${REA_PACKAGE}@${version}`,
+		files,
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	await writeFile(join(tree, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+	await rm(root, {
+		recursive: true,
+		force: true
+	});
+	await rename(tree, root);
+	await rm(staging, {
+		recursive: true,
+		force: true
+	});
+	deps.refresh();
+	ctx.log(`已更新 skill ${REA_SKILL_NAME}（${files.length} 文件）→ ${root}`);
+	return version;
+}
+/** 生效配置：作业可带一次性覆盖（卡片未保存的代理端口即时可用）。 */
+function configWith(base, overrides) {
+	if (overrides?.proxyPort === void 0) return base;
+	return {
+		...base,
+		proxyPort: overrides.proxyPort
+	};
+}
+/** 建一个 REA 管理器。 */
+function createManager(options) {
+	const runner = options.runner ?? spawnRunner;
+	const paths = () => managerPaths(options.config());
+	let cache = null;
+	const refresh = () => {
+		cache = probeRuntime(options.config(), options.bundledRoot, options.bundledVersion);
+		return cache;
+	};
+	return {
+		paths,
+		refresh,
+		snapshot: () => cache ?? refresh(),
+		operations: (overrides) => {
+			const deps = {
+				config: configWith(options.config(), overrides),
+				runner,
+				refresh
+			};
+			return {
+				install: {
+					phases: INSTALL_PHASES,
+					run: (ctx) => runInstallJob(deps, ctx)
 				},
-				config: [
-					{
-						id: "compaction-basic",
-						name: "@deepseek-ai/dsh-compaction-basic"
-					},
-					{
-						id: "command-compact",
-						name: "@deepseek-ai/dsh-command-compact"
-					},
-					{
-						id: "tool-result-pruner",
-						name: "@deepseek-ai/dsh-compaction-tool-result-pruner",
-						config: {
-							thresholdChars: 8192,
-							headChars: 4096,
-							tailChars: 1024
-						}
-					}
-				]
-			},
-			{
-				id: "delegation",
-				name: GROUP,
-				group: true,
-				isolate: { workflowEngine: true },
-				config: [
-					{
-						id: "tool-subagent-control",
-						name: "@deepseek-ai/dsh-tool-subagent-control"
-					},
-					{
-						id: "tool-subagent-list-agents",
-						name: "@deepseek-ai/dsh-tool-subagent-control/list-agents"
-					},
-					{
-						id: "tool-subagent",
-						name: "@deepseek-ai/dsh-tool-subagent",
-						config: {
-							provider: "spawn",
-							toolName: "subagent",
-							modelSelectionSettings: true
-						}
-					},
-					{
-						id: "tool-subagent-fork",
-						name: "@deepseek-ai/dsh-tool-subagent",
-						config: {
-							provider: "fork",
-							toolName: "subagent_fork"
-						}
-					},
-					{
-						id: "workflow-ptc",
-						name: "@deepseek-ai/dsh-workflow-ptc",
-						config: { provider: "spawn" }
-					},
-					{
-						id: "tool-workflow",
-						name: "@deepseek-ai/dsh-tool-workflow"
-					}
-				]
-			},
-			{
-				id: "tool-ask-user",
-				name: "@deepseek-ai/dsh-tool-ask-user"
-			},
-			{
-				id: "tool-todo",
-				name: "@deepseek-ai/dsh-tool-todo",
-				config: { allowParallelInProgress: true }
-			},
-			{
-				id: "tool-web",
-				name: "@deepseek-ai/dsh-tool-web",
-				config: {
-					fetch: true,
-					searchTimeoutMs: 6e4
-				}
-			},
-			{
-				id: "mcp-rea",
-				name: "@deepseek-ai/dsh-mcp-client",
-				disabled: !config.mcpEnabled,
-				config: {
-					transport: "stdio",
-					serverName: config.mcpServerName,
-					command: config.mcpCommand,
-					args: reaMcpArgs(config),
-					env: reaMcpEnv(config),
-					toolCallTimeoutMs: config.toolCallTimeoutMs,
-					failOnStartupError: config.failOnStartupError
+				skill: {
+					phases: SKILL_PHASES,
+					run: (ctx) => runSkillJob(deps, ctx)
+				},
+				reverse: {
+					phases: REVERSE_PHASES,
+					run: (ctx) => runReverseSkillJob(deps, ctx)
 				}
-			},
-			{
-				id: "present",
-				name: "@deepseek-ai/dsh-tool-present"
-			},
-			{
-				id: "tool-plugin-manager",
-				name: "@deepseek-ai/dsh-plugin-manager/tools",
-				disabled: true
-			}
-		]
+			};
+		}
 	};
 }
 //#endregion
@@ -383,6 +1312,169 @@ function createPresetRegistrar(options) {
 	};
 }
 //#endregion
+//#region src/routes.ts
+/** 路由前缀。 */
+const ROUTE_BASE = "/dsh-plus/agent-preset-rea";
+/** 请求体大小上限（只有一个数字字段）。 */
+const BODY_LIMIT = 4096;
+/** 读请求体（超限即拒绝；空体按空对象）。 */
+async function readBody(req) {
+	const chunks = [];
+	let size = 0;
+	for await (const chunk of req) {
+		const buf = chunk;
+		size += buf.length;
+		if (size > BODY_LIMIT) throw new Error("请求体过大");
+		chunks.push(buf);
+	}
+	const text = Buffer.concat(chunks).toString("utf8").trim();
+	return text === "" ? {} : JSON.parse(text);
+}
+/** 从请求体取可选的代理端口覆盖（形状不对即抛，由调用方回 400）。 */
+function proxyPortOf(body) {
+	if (typeof body !== "object" || body === null) return void 0;
+	const value = body["proxyPort"];
+	if (value === void 0 || value === null) return void 0;
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > 65535) throw new Error("proxyPort 必须是 0..65535 的整数");
+	return value;
+}
+/** 组装状态响应（纯函数，可直接单测）。 */
+function statusPayload(options) {
+	const config = options.config();
+	const runtime = options.manager.snapshot();
+	const paths = options.manager.paths();
+	const launch = reaMcpLaunch(config, runtime.install);
+	const mode = config.mcpCommand.trim() !== "" ? "custom" : launch === null ? "missing" : "installed";
+	const reverse = reversePaths();
+	const activeDirs = reverseSkillDirs(config, runtime.reverse);
+	return {
+		config: {
+			reaVersion: config.reaVersion,
+			proxyPort: config.proxyPort,
+			mcpEnabled: config.mcpEnabled,
+			skillEnabled: config.skillEnabled,
+			reverseSkillEnabled: config.reverseSkillEnabled,
+			reverseSkillRepo: config.reverseSkillRepo,
+			reverseSkillRef: config.reverseSkillRef,
+			reverseSkillGroups: [...config.reverseSkillGroups],
+			installRoot: config.installRoot
+		},
+		install: {
+			installed: runtime.install !== null,
+			version: runtime.install?.version ?? null,
+			root: paths.installRoot,
+			entry: runtime.install?.entry ?? null
+		},
+		skill: { ...runtime.skill },
+		reverse: {
+			installed: runtime.reverse.installed,
+			repo: runtime.reverse.repo,
+			ref: runtime.reverse.ref,
+			sha: runtime.reverse.sha,
+			version: runtime.reverse.version,
+			root: reverse.root,
+			tree: reverse.tree,
+			files: runtime.reverse.files,
+			groups: [...runtime.reverse.groups],
+			activeGroups: activeDirs.map((dir) => dir.startsWith(`${reverse.tree}/`) ? dir.slice(reverse.tree.length + 1) : dir),
+			updatedAt: runtime.reverse.updatedAt
+		},
+		mcp: {
+			mode,
+			enabled: config.mcpEnabled && launch !== null,
+			command: launch?.command ?? null,
+			args: launch?.args ?? []
+		},
+		paths: {
+			...paths,
+			reverseRoot: reverse.root
+		},
+		job: options.board.snapshot()
+	};
+}
+/** 发送 JSON 响应。 */
+function makeSend() {
+	return (res, status, body) => {
+		res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+		res.end(JSON.stringify(body));
+	};
+}
+/** 异常兜底：日志 + 400（响应头已发则只收尾）。 */
+function makeGuard(logger, send) {
+	return (handler) => async (req, res) => {
+		try {
+			await handler(req, res);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			logger.warn(`${req.method ?? "?"} ${req.url ?? "?"} 失败：${message}`);
+			if (!res.headersSent) send(res, 400, {
+				job: null,
+				error: message
+			});
+			else res.end();
+		}
+	};
+}
+/** 方法门：不匹配即 405。 */
+function withMethod(method, send, handler) {
+	return async (req, res) => {
+		if (req.method !== method) {
+			send(res, 405, {
+				job: null,
+				error: "method not allowed"
+			});
+			return;
+		}
+		await handler(req, res);
+	};
+}
+/** 起作业的处理器工厂（409 = 已有作业在跑）。 */
+function startJobHandler(kind, options, logger, send) {
+	return async (req, res) => {
+		const overrides = proxyPortOf(await readBody(req));
+		const operations = options.manager.operations(overrides === void 0 ? void 0 : { proxyPort: overrides });
+		const job = options.board.start(kind, operations[kind]);
+		if (job === null) {
+			send(res, 409, {
+				job: options.board.snapshot(),
+				error: "已有作业在运行"
+			});
+			return;
+		}
+		logger.info(`已启动 ${kind} 作业`);
+		send(res, 200, { job });
+	};
+}
+/** 全部路由（path 末段 → 处理器）。 */
+function buildRoutes(options, logger, send) {
+	return {
+		status: withMethod("GET", send, async (_req, res) => {
+			send(res, 200, statusPayload(options));
+		}),
+		install: withMethod("POST", send, startJobHandler("install", options, logger, send)),
+		skill: withMethod("POST", send, startJobHandler("skill", options, logger, send)),
+		reverse: withMethod("POST", send, startJobHandler("reverse", options, logger, send)),
+		cancel: withMethod("POST", send, async (_req, res) => {
+			const cancelled = options.board.cancel();
+			send(res, 200, {
+				job: options.board.snapshot(),
+				...cancelled ? {} : { error: "没有正在运行的作业" }
+			});
+		})
+	};
+}
+/** 注册全部路由。 */
+function registerReaRoutes(ctx, options) {
+	const logger = ctx.logger("agent-preset-rea");
+	const send = makeSend();
+	const guard = makeGuard(logger, send);
+	for (const [name, handler] of Object.entries(buildRoutes(options, logger, send))) ctx.webServer.register({
+		kind: "exact",
+		path: `${ROUTE_BASE}/${name}`,
+		handler: guard(handler)
+	});
+}
+//#endregion
 //#region src/index.ts
 const name = "dsh-plus-agent-preset-rea";
 /** 无硬 inject：agentPresets 经 apply 内惰性 inject 接线（缺席即空转）。 */
@@ -403,20 +1495,44 @@ function apply(ctx, config) {
 		const detail = error instanceof Error ? error.message : String(error);
 		logger.warn(`register rea preset failed: ${detail}`);
 	};
+	const manager = createManager({
+		config: current,
+		bundledRoot: BUNDLED_SKILL_ROOT,
+		bundledVersion: REA_PINNED_VERSION
+	});
+	const board = createJobBoard();
+	let reregister = null;
+	const refresh = () => {
+		manager.refresh();
+		reregister?.();
+	};
+	ctx.effect(() => board.onSettled((snapshot) => {
+		refresh();
+		logger.info(`rea ${snapshot.kind} 作业结束：${snapshot.state}`);
+	}), "agent-preset-rea: refresh after job");
 	ctx.inject(["agentPresets"], (scope) => {
 		scope.effect(() => {
 			const registrar = createPresetRegistrar({
 				register: (definition) => scope.agentPresets.register(definition),
-				build: () => reaPresetDefinition(current()),
+				build: () => reaPresetDefinition(current(), manager.snapshot()),
 				onError
 			});
-			const off = ctx.events.on("loader/volatile-update", () => registrar.refresh());
+			reregister = () => registrar.refresh();
+			const off = ctx.events.on("loader/volatile-update", () => refresh());
 			return () => {
+				reregister = null;
 				off();
 				registrar.dispose();
 			};
 		}, "agent-preset-rea: register rea preset");
 	});
+	ctx.inject(["webServer"], (scope) => {
+		registerReaRoutes(scope, {
+			manager,
+			board,
+			config: current
+		});
+	});
 }
 //#endregion
-export { ADDED_ROWS, BUNDLED_SKILL_ROOT, CONFIG_DELTAS, Config, DEFAULT_MCP_COMMAND, INPUT_SCHEMA_PROFILES, OUTPUT_SCHEMA_PROFILES, PLAN_MODE_SECTION, REA_PINNED_VERSION, REA_PRESET_ID, SETTINGS_NS, apply, createPresetRegistrar, inject, name, reaMcpArgs, reaMcpEnv, reaPresetDefinition, reaSkillDirs };
+export { ADDED_ROWS, BUNDLED_SKILL_ROOT, CONFIG_DELTAS, Config, DEFAULT_MCP_COMMAND, INPUT_SCHEMA_PROFILES, INSTALL_PHASES, JobCancelled, NPM, OUTPUT_SCHEMA_PROFILES, PLAN_MODE_SECTION, REA_INSTALL_DIR, REA_PACKAGE, REA_PINNED_VERSION, REA_PRESET_ID, REA_SKILL_DIR, REA_SKILL_NAME, REVERSE_DEFAULT_REPO, REVERSE_DIR, REVERSE_PHASES, REVERSE_TREE_DIR, ROUTE_BASE, SETTINGS_NS, SKILL_PHASES, apply, configWith, createJobBoard, createManager, createPresetRegistrar, discoverSkillGroups, emptyRuntime, inject, managerPaths, name, npmEnv, presetSkillDirs, probeInstall, probeReverse, probeRuntime, probeSkill, reaMcpArgs, reaMcpEnv, reaMcpLaunch, reaPresetDefinition, reaSkillDirs, registerReaRoutes, reversePaths, reverseSkillDirs, runReverseSkillJob, safeVersion, spawnRunner, statusPayload };