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

package/src/reverse.ts

@@ -0,0 +1,335 @@
+/**
+ * 第二个受管技能源：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
+ */
+import { type Dirent, existsSync, readdirSync, readFileSync } from 'node:fs'
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { pluginDataPath } from '@dsh-plus/shared'
+
+import type { AgentPresetReaConfig } from './config.ts'
+import {
+  commandEnv,
+  countFiles,
+  type JobDeps,
+  type JobTaskContext,
+  lineSink,
+  proxyUrl,
+} from './exec.ts'
+
+/** 插件数据目录标识（与 manager.ts 同源：`<DSH_HOME>/dsh-plus/<id>`）。 */
+const PLUGIN_ID = 'dsh-plus-agent-preset-rea'
+
+/** 本技能源在插件数据目录下的子目录名。 */
+export const REVERSE_DIR = 'reverse-skill'
+
+/** 仓库树目录名（换目录作业的替换单元是它的父目录）。 */
+export const REVERSE_TREE_DIR = 'repo'
+
+/** 默认仓库。 */
+export const REVERSE_DEFAULT_REPO = 'zhaoxuya520/reverse-skill'
+
+/** 手动更新作业阶段名。 */
+export const REVERSE_PHASES: string[] = ['解析仓库信息', '下载源码包', '解包源码', '校验并写入清单']
+
+/** 不参与技能组发现的目录名（客户端打包产物；会重复一遍路由技能）。 */
+const SKIP_DIRS = new Set(['.git', 'plugins', 'node_modules'])
+
+/** 受管路径。 */
+export interface ReversePaths {
+  /** 技能源根（`repo/` 与 `manifest.json` 的父目录）。 */
+  root: string
+  /** 仓库树根。 */
+  tree: string
+}
+
+/** 清单（溯源事实；sha 已是内容级溯源，故不再逐文件复算哈希）。 */
+export interface ReverseManifest {
+  source: string
+  repo: string
+  /** 配置里的 ref（空串 = 仓库默认分支）。 */
+  ref: string
+  /** GitHub 机构 API 解析到的提交 sha。 */
+  sha: string
+  /** 仓库 `VERSION` 文件内容（无则 null）。 */
+  version: string | null
+  /** 树内文件数。 */
+  files: number
+  /** 树内发现的技能组（相对路径）。 */
+  groups: string[]
+  updatedAt: string
+}
+
+/** 技能源现状。 */
+export interface ReverseState {
+  installed: boolean
+  repo: string
+  ref: string | null
+  sha: string | null
+  version: string | null
+  files: number
+  /** 树内发现的全部技能组（相对路径）。 */
+  groups: string[]
+  updatedAt: string | null
+}
+
+/** 未安装时的现状（导出给 emptyRuntime 等默认场景用）。 */
+export function emptyReverseState(repo = REVERSE_DEFAULT_REPO): ReverseState {
+  return missingState(repo)
+}
+
+/** 未安装时的现状。 */
+function missingState(repo: string): ReverseState {
+  return {
+    installed: false,
+    repo,
+    ref: null,
+    sha: null,
+    version: null,
+    files: 0,
+    groups: [],
+    updatedAt: null,
+  }
+}
+
+/** 受管路径（固定落插件数据目录，无部署方可调项）。 */
+export function reversePaths(): ReversePaths {
+  const root = pluginDataPath(PLUGIN_ID, REVERSE_DIR)
+  return { root, tree: join(root, REVERSE_TREE_DIR) }
+}
+
+/** 读 JSON（不存在或坏内容返回 null）。 */
+function readJson(file: string): unknown {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8')) as unknown
+  } catch {
+    return null
+  }
+}
+
+/** 记录型守卫。 */
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : null
+}
+
+/** 直接子目录名（跳过不参与发现的目录；目录读不到按无子目录）。 */
+function subdirs(dir: string): string[] {
+  let entries: Dirent[]
+  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）。 */
+export function discoverSkillGroups(tree: string): string[] {
+  const groups: string[] = []
+  const walk = (rel: string): void => {
+    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 !== '')
+}
+
+/** 现探技能源（清单可读 + 树在 + 至少一个技能组才算可用）。 */
+export function probeReverse(
+  config: AgentPresetReaConfig,
+  repo = config.reverseSkillRepo,
+): ReverseState {
+  const { root, tree } = reversePaths()
+  const manifest = asRecord(readJson(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 - 现探现状。
+ */
+export function reverseSkillDirs(config: AgentPresetReaConfig, state: ReverseState): string[] {
+  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))
+}
+
+/** 作业依赖（与 manager 的作业同形：配置 + 命令执行面 + 现探刷新）。 */
+export type ReverseDeps = JobDeps
+
+/** curl 通用参数：失败即非零退出、跟随跳转、静默进度。 */
+function curlArgs(config: AgentPresetReaConfig): string[] {
+  const proxy = proxyUrl(config)
+  return ['-fsSL', ...(proxy === null ? [] : ['-x', proxy])]
+}
+
+/** 跑一次 curl 并落文件（失败抛错）。 */
+async function curl(
+  deps: ReverseDeps,
+  ctx: JobTaskContext,
+  args: string[],
+  target: string,
+): Promise<void> {
+  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: ReverseDeps,
+  ctx: JobTaskContext,
+  staging: string,
+): Promise<{ sha: string; ref: string }> {
+  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(readJson(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(readJson(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: ReverseDeps, ctx: JobTaskContext, staging: string): Promise<string> {
+  const { sha } = await resolveRepo(deps, ctx, staging)
+  // 树目录名与 {@link reversePaths} 对齐：staging 顶掉旧根后即 `<root>/repo`。
+  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: string): string | null {
+  try {
+    const text = readFileSync(join(tree, 'VERSION'), 'utf8').trim()
+    return text === '' ? null : (text.split('\n')[0] ?? null)
+  } catch {
+    return null
+  }
+}
+
+/** 手动更新作业：拉默认分支/指定 ref 的最新提交，解包后换目录并写清单。 */
+export async function runReverseSkillJob(deps: ReverseDeps, ctx: JobTaskContext): Promise<string> {
+  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(readJson(join(staging, 'commit.json')))
+    const sha = typeof meta?.['sha'] === 'string' ? meta['sha'] : ''
+    // 换目录前清掉作业草稿（tarball 与 API 响应都只是取数中间物，不该留在受管根里）。
+    for (const scratch of ['repo.tgz', 'meta.json', 'commit.json']) {
+      await rm(join(staging, scratch), { force: true })
+    }
+    const manifest: ReverseManifest = {
+      source: `github:${deps.config.reverseSkillRepo}@${sha}`,
+      repo: deps.config.reverseSkillRepo,
+      ref: deps.config.reverseSkillRef.trim(),
+      sha,
+      version: readVersion(tree),
+      files: countFiles(tree),
+      groups,
+      updatedAt: new Date().toISOString(),
+    }
+    await writeFile(join(staging, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`)
+
+    // 换目录：staging 顶掉旧根，旧根留 .old 再清（失败时旧树仍完整可用）。
+    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
+  }
+}

package/src/routes.ts

@@ -0,0 +1,223 @@
+/**
+ * 受管安装/更新的 HTTP 通道：状态查询 + 四类动作（安装/更新 REA、更新 REA skill、
+ * 更新 reverse-skill、取消作业）。
+ *
+ * 只挂在 dsh web 同源（webserver 默认 127.0.0.1，与 notify-email 的测试端点同等暴露面）：
+ * 这些端点会 spawn npm/curl 并写插件数据目录，不做鉴权以外的额外暴露面扩张。
+ * 配置读写仍走官方 settings（卡片直连 remote.settings），这里只补官方传输没有的动作。
+ *
+ * 请求体只接受一个可选字段 `proxyPort`（0..65535）；其余一律来自插件配置。
+ * @module @dsh-plus/agent-preset-rea/routes
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+import type { Context } from '@deepseek-ai/cordis'
+// 平台声明导入（无值消费）：把 webServer 服务面合进 program，ctx.webServer 方可解析。
+import type {} from '@deepseek-ai/dsh-host-webserver'
+
+import type { AgentPresetReaConfig } from './config.ts'
+import type { JobActionDto, JobKind, StatusDto } from './dto.ts'
+import type { JobBoard } from './jobs.ts'
+import type { ReaManager } from './manager.ts'
+import { type McpLaunch, reaMcpLaunch } from './mcp.ts'
+import { reversePaths, reverseSkillDirs } from './reverse.ts'
+
+/** 路由前缀。 */
+export const ROUTE_BASE = '/dsh-plus/agent-preset-rea'
+
+/** 请求体大小上限（只有一个数字字段）。 */
+const BODY_LIMIT = 4096
+
+/** 路由依赖。 */
+export interface ReaRoutesOptions {
+  manager: ReaManager
+  board: JobBoard
+  config: () => AgentPresetReaConfig
+}
+
+/** 路由处理器形态。 */
+type RouteHandler = (req: IncomingMessage, res: ServerResponse) => Promise<void>
+
+/** 响应发送器。 */
+type Send = (res: ServerResponse, status: number, body: unknown) => void
+
+/** 日志窄面。 */
+interface RouteLogger {
+  info(message: string): void
+  warn(message: string): void
+}
+
+/** 读请求体（超限即拒绝；空体按空对象）。 */
+async function readBody(req: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = []
+  let size = 0
+  for await (const chunk of req) {
+    const buf = chunk as Buffer
+    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) as unknown)
+}
+
+/** 从请求体取可选的代理端口覆盖（形状不对即抛，由调用方回 400）。 */
+function proxyPortOf(body: unknown): number | undefined {
+  if (typeof body !== 'object' || body === null) return undefined
+  const value = (body as Record<string, unknown>)['proxyPort']
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > 65535) {
+    throw new Error('proxyPort 必须是 0..65535 的整数')
+  }
+  return value
+}
+
+/** 组装状态响应（纯函数，可直接单测）。 */
+export function statusPayload(options: ReaRoutesOptions): StatusDto {
+  const config = options.config()
+  const runtime = options.manager.snapshot()
+  const paths = options.manager.paths()
+  const launch: McpLaunch | null = 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(): Send {
+  return (res, status, body) => {
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' })
+    res.end(JSON.stringify(body))
+  }
+}
+
+/** 异常兜底：日志 + 400（响应头已发则只收尾）。 */
+function makeGuard(logger: RouteLogger, send: Send): (handler: RouteHandler) => RouteHandler {
+  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 } satisfies JobActionDto)
+      else res.end()
+    }
+  }
+}
+
+/** 方法门：不匹配即 405。 */
+function withMethod(method: string, send: Send, handler: RouteHandler): RouteHandler {
+  return async (req, res) => {
+    if (req.method !== method) {
+      send(res, 405, { job: null, error: 'method not allowed' } satisfies JobActionDto)
+      return
+    }
+    await handler(req, res)
+  }
+}
+
+/** 起作业的处理器工厂（409 = 已有作业在跑）。 */
+function startJobHandler(
+  kind: JobKind,
+  options: ReaRoutesOptions,
+  logger: RouteLogger,
+  send: Send,
+): RouteHandler {
+  return async (req, res) => {
+    const overrides = proxyPortOf(await readBody(req))
+    const operations = options.manager.operations(
+      overrides === undefined ? undefined : { proxyPort: overrides },
+    )
+    const job = options.board.start(kind, operations[kind])
+    if (job === null) {
+      send(res, 409, {
+        job: options.board.snapshot(),
+        error: '已有作业在运行',
+      } satisfies JobActionDto)
+      return
+    }
+    logger.info(`已启动 ${kind} 作业`)
+    send(res, 200, { job } satisfies JobActionDto)
+  }
+}
+
+/** 全部路由（path 末段 → 处理器）。 */
+function buildRoutes(
+  options: ReaRoutesOptions,
+  logger: RouteLogger,
+  send: Send,
+): Record<string, RouteHandler> {
+  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: '没有正在运行的作业' }),
+      } satisfies JobActionDto)
+    }),
+  }
+}
+
+/** 注册全部路由。 */
+export function registerReaRoutes(ctx: Context, options: ReaRoutesOptions): void {
+  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),
+    })
+  }
+}

package/src/skill.ts

@@ -1,14 +1,18 @@
 /**
- * 预设作用域内的 skill 根解析：随包 REA 官方 skill + 配置追加目录。
+ * 预设作用域内的 skill 根解析：随包 REA 官方 skill（或手动更新副本）+ 配置追加目录。
  *
- * 两者都只加在本预设 `skill-filesystem` 行的 `customSkillDirs`（rank 300 的
- * **追加**根）上，因此不会进入项目根 / 用户根 / `$DSH_BUNDLED_SKILL_DIR`，
- * 其他预设的 skill 目录不受影响。
+ * 全部只加在本预设 `skill-filesystem` 行的 `customSkillDirs`（rank 300 的**追加**根）
+ * 上，因此不进入项目根 / 用户根 / `$DSH_BUNDLED_SKILL_DIR`，其他预设不受影响。
+ *
+ * 手动更新副本存在时**替代**随包根而不是并排：两者同名（`reverse-engineer-anything`），
+ * 并排只会得到「哪个生效」的歧义。
  * @module @dsh-plus/agent-preset-rea/skill
  */
 import { fileURLToPath } from 'node:url'
 
 import type { AgentPresetReaConfig } from './config.ts'
+import type { RuntimeSnapshot } from './manager.ts'
+import { reverseSkillDirs } from './reverse.ts'
 
 /**
  * 随包 REA 官方 skill 根（包内 `skills/`）。
@@ -18,7 +22,28 @@ import type { AgentPresetReaConfig } from './config.ts'
  */
 export const BUNDLED_SKILL_ROOT = fileURLToPath(new URL('../skills', import.meta.url))
 
-/** skill-filesystem 的追加根清单：随包 REA skill 在前，配置追加目录随后。 */
-export function reaSkillDirs(config: AgentPresetReaConfig): string[] {
-  return [BUNDLED_SKILL_ROOT, ...config.extraSkillDirs]
+/**
+ * REA skill 根（随包副本，或手动更新副本——后者存在即替代前者）。
+ * @param updatedRoot - 手动更新副本根（来自 manager 现探）。
+ */
+export function reaSkillDirs(updatedRoot: string | null = null): string[] {
+  return updatedRoot === null ? [BUNDLED_SKILL_ROOT] : [updatedRoot]
+}
+
+/**
+ * 本预设 `skill-filesystem` 行的完整追加根清单，按三个开关裁剪：
+ * - `skillEnabled=false` → 不挂 REA 官方 skill（安装副本仍留在磁盘）；
+ * - `reverseSkillEnabled=false` → 不挂 reverse-skill 的技能组；
+ * - `extraSkillDirs` 是部署方追加项，不受开关影响（关掉的是本插件自带的两个源）。
+ * @param config - 插件配置。
+ * @param runtime - 现探运行期事实。
+ */
+export function presetSkillDirs(config: AgentPresetReaConfig, runtime: RuntimeSnapshot): string[] {
+  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]
 }