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

package/src/definition.ts

@@ -8,7 +8,8 @@
  *
  * 增量仅三处，测试按 {@link ADDED_ROWS} / {@link CONFIG_DELTAS} 白名单放行：
  * 1. `persona` 行 `prefix` 取配置值（默认空串 = 空 persona）；
- * 2. `skill-filesystem` 行加 `customSkillDirs`（随包 REA skill 或手动更新副本 + 追加目录）；
+ * 2. `skill-filesystem` 行加 `customSkillDirs`（REA skill 源与 reverse-skill 技能组，
+ *    各受一个活动开关控制，另加部署方 `extraSkillDirs`）；
  * 3. 新增 `mcp-rea` 行：官方 MCP 客户端连 REA stdio 服务，落在本预设作用域内；
  *    **未安装 REA 时该行 `disabled`**（不 spawn npx，见 mcp.ts 的说明）。
  *
@@ -24,7 +25,8 @@ import type { AgentPresetReaConfig } from './config.ts'
 import type { RuntimeSnapshot } from './manager.ts'
 import { DEFAULT_MCP_COMMAND, reaMcpArgs, reaMcpEnv, reaMcpLaunch } from './mcp.ts'
 import { PLAN_MODE_SECTION } from './prompt.ts'
-import { BUNDLED_SKILL_ROOT, reaSkillDirs } from './skill.ts'
+import { emptyReverseState } from './reverse.ts'
+import { BUNDLED_SKILL_ROOT, presetSkillDirs } from './skill.ts'
 
 /** 预设注册表身份（改 id 等于换预设，default 等引用都会落空）。 */
 export const REA_PRESET_ID = 'rea'
@@ -58,6 +60,7 @@ export function emptyRuntime(): RuntimeSnapshot {
       files: 0,
       updatedAt: null,
     },
+    reverse: emptyReverseState(),
   }
 }
 
@@ -102,10 +105,7 @@ function baseRows(config: AgentPresetReaConfig, runtime: RuntimeSnapshot): Row[]
       id: 'skill-filesystem',
       name: '@deepseek-ai/dsh-skill-filesystem',
       config: {
-        customSkillDirs: reaSkillDirs(
-          config,
-          runtime.skill.source === 'updated' ? runtime.skill.root : null,
-        ),
+        customSkillDirs: presetSkillDirs(config, runtime),
       },
     },
     { id: 'tool-skill', name: '@deepseek-ai/dsh-tool-skill' },

package/src/dto.ts

@@ -6,8 +6,8 @@
  * @module @dsh-plus/agent-preset-rea/dto
  */
 
-/** 作业种类。 */
-export type JobKind = 'install' | 'skill'
+/** 作业种类：REA 包安装/更新、REA skill 更新、reverse-skill 更新。 */
+export type JobKind = 'install' | 'skill' | 'reverse'
 
 /** 作业状态。 */
 export type JobState = 'running' | 'ok' | 'error' | 'cancelled'
@@ -64,18 +64,44 @@ export interface McpDto {
   args: string[]
 }
 
+/** GitHub 技能源（zhaoxuya520/reverse-skill）事实。 */
+export interface ReverseSkillDto {
+  installed: boolean
+  repo: string
+  /** 清单记录的 ref（空串 = 安装时取的默认分支）。 */
+  ref: string | null
+  /** 提交 sha（内容级溯源）。 */
+  sha: string | null
+  /** 仓库 VERSION 文件内容。 */
+  version: string | null
+  root: string
+  tree: string
+  files: number
+  /** 树内发现的全部技能组（相对安装树根）。 */
+  groups: string[]
+  /** 配置选中且实际挂进预设的组。 */
+  activeGroups: string[]
+  updatedAt: string | null
+}
+
 /** `GET /status` 响应。 */
 export interface StatusDto {
   config: {
     reaVersion: string
     proxyPort: number
     mcpEnabled: boolean
+    skillEnabled: boolean
+    reverseSkillEnabled: boolean
+    reverseSkillRepo: string
+    reverseSkillRef: string
+    reverseSkillGroups: string[]
     installRoot: string
   }
   install: InstallDto
   skill: SkillDto
+  reverse: ReverseSkillDto
   mcp: McpDto
-  paths: { installRoot: string; skillRoot: string }
+  paths: { installRoot: string; skillRoot: string; reverseRoot: string }
   job: JobDto | null
 }
 

package/src/exec.ts

@@ -53,6 +53,13 @@ export interface JobOperation {
   run(ctx: JobTaskContext): Promise<string>
 }
 
+/** 作业依赖：生效配置、命令执行面、作业完成后的现探刷新。 */
+export interface JobDeps {
+  config: AgentPresetReaConfig
+  runner: CommandRunner
+  refresh(): void
+}
+
 /** 实际 runner：spawn 子进程、逐行回调、AbortSignal 触发即杀。 */
 export const spawnRunner: CommandRunner = {
   run: (command, args, options) =>
@@ -90,32 +97,47 @@ export const spawnRunner: CommandRunner = {
     }),
 }
 
+/** 本机代理 URL（未配置代理时为 null）。 */
+export function proxyUrl(config: AgentPresetReaConfig): string | null {
+  return config.proxyPort > 0 ? `http://127.0.0.1:${config.proxyPort}` : null
+}
+
 /**
- * npm 子进程环境：继承宿主环境，附带代理端口（port > 0 时同时给 npm 与
- * prebuild-install 注入代理——后者只认 `https_proxy` 系列环境变量，
- * 这是原生依赖 prebuild 下载卡死的正解）。
+ * 子进程环境：继承宿主环境，附带代理端口（port > 0 时给 `https_proxy` 系列，
+ * prebuild-install 与 curl 都认这些变量——原生依赖 prebuild 下载卡死的正解）。
+ * @param config - 插件配置。
+ * @param npm - 是否附带 npm 专属开关（npm 子进程用；curl 等非 npm 命令不需要）。
  */
-export function npmEnv(config: AgentPresetReaConfig): Record<string, string> {
+export function commandEnv(config: AgentPresetReaConfig, npm = false): Record<string, string> {
   const env: Record<string, string> = {}
   for (const [key, value] of Object.entries(process.env)) {
     if (value !== undefined) env[key] = value
   }
-  env['npm_config_audit'] = 'false'
-  env['npm_config_fund'] = 'false'
-  env['npm_config_update_notifier'] = 'false'
-  env['npm_config_loglevel'] = 'http'
-  if (config.proxyPort > 0) {
-    const proxy = `http://127.0.0.1:${config.proxyPort}`
+  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
-    env['npm_config_proxy'] = proxy
-    env['npm_config_https_proxy'] = proxy
+    if (npm) {
+      env['npm_config_proxy'] = proxy
+      env['npm_config_https_proxy'] = proxy
+    }
   }
   return env
 }
 
+/** npm 子进程环境（{@link commandEnv} 的 npm 形态）。 */
+export function npmEnv(config: AgentPresetReaConfig): Record<string, string> {
+  return commandEnv(config, true)
+}
+
 /** 版本收窄：进命令前把配置里的钉版校验成纯版本号。 */
 export function safeVersion(version: string): string {
   const trimmed = version.trim()

package/src/index.ts

@@ -18,6 +18,11 @@
  * 本插件据此换代注册（注销旧声明 → 按新值重建声明），**新建会话**即用新提示词，
  * 已存在会话保持既有 composition（注册表语义：运行中会话的装配不随换代改变）。
  *
+ * 卡片上还有三个能力开关（活动字段：REA MCP 行、REA skill、reverse-skill 技能包）
+ * 与两个受管技能源的手动更新：REA 官方 skill（npm 包内 `skills/`）与 GitHub 的
+ * `zhaoxuya520/reverse-skill`（路由包，按技能组挂进 `customSkillDirs`）。开关只管
+ * 挂不挂，安装副本始终留在插件数据目录。
+ *
  * REA 的安装与更新也在卡片上（受管安装 + 后台作业 + 实时进度 + 可选代理端口）：
  * 宿主半的 manager 把 `rea-agents` 装进插件数据目录、把 skill 拉成可替换副本，
  * 作业完成后同样换代注册——因此预设声明里**不会**在 boot 期 spawn `npx`
@@ -69,6 +74,7 @@ export type {
   JobProgressDto,
   JobState,
   McpDto,
+  ReverseSkillDto,
   SkillDto,
   StatusDto,
 } from './dto.ts'
@@ -118,8 +124,22 @@ export {
 } from './mcp.ts'
 export { PLAN_MODE_SECTION } from './prompt.ts'
 export { createPresetRegistrar, type PresetRegistrar, type Unregister } from './registration.ts'
+export {
+  discoverSkillGroups,
+  probeReverse,
+  REVERSE_DEFAULT_REPO,
+  REVERSE_DIR,
+  REVERSE_PHASES,
+  REVERSE_TREE_DIR,
+  type ReverseManifest,
+  type ReversePaths,
+  type ReverseState,
+  reversePaths,
+  reverseSkillDirs,
+  runReverseSkillJob,
+} from './reverse.ts'
 export { ROUTE_BASE, registerReaRoutes, statusPayload } from './routes.ts'
-export { BUNDLED_SKILL_ROOT, reaSkillDirs } from './skill.ts'
+export { BUNDLED_SKILL_ROOT, presetSkillDirs, reaSkillDirs } from './skill.ts'
 export type { AgentPresetReaConfig, AgentPresetReaConfigFields }
 export { Config }
 

package/src/manager.ts

@@ -30,6 +30,7 @@ import type { AgentPresetReaConfig } from './config.ts'
 import {
   type CommandRunner,
   countFiles,
+  type JobDeps,
   type JobOperation,
   type JobTaskContext,
   lineSink,
@@ -39,6 +40,9 @@ import {
   safeVersion,
   spawnRunner,
 } from './exec.ts'
+import { probeReverse, REVERSE_PHASES, type ReverseState, runReverseSkillJob } from './reverse.ts'
+
+export type { JobDeps }
 
 /** npm 包名。 */
 export const REA_PACKAGE = 'rea-agents'
@@ -80,6 +84,8 @@ export interface SkillState {
 export interface RuntimeSnapshot {
   install: ReaInstall | null
   skill: SkillState
+  /** GitHub 技能源（zhaoxuya520/reverse-skill）现状。 */
+  reverse: ReverseState
 }
 
 /** skill 清单（与随包夹具同形；更新副本多写入 updatedAt）。 */
@@ -107,8 +113,12 @@ export interface ReaManager {
   snapshot(): RuntimeSnapshot
   /** 重新现探并更新快照（作业完成、volatile 变更后调用）。 */
   refresh(): RuntimeSnapshot
-  /** 受管作业（安装/更新 REA 包、更新 skill）。 */
-  operations(overrides?: JobOverrides): { install: JobOperation; skill: JobOperation }
+  /** 受管作业（安装/更新 REA 包、更新 REA skill、更新 reverse-skill）。 */
+  operations(overrides?: JobOverrides): {
+    install: JobOperation
+    skill: JobOperation
+    reverse: JobOperation
+  }
 }
 
 /** 安装作业阶段名。 */
@@ -219,16 +229,10 @@ export function probeRuntime(
   return {
     install: probeInstall(paths),
     skill: probeSkill(paths, bundledRoot, bundledVersion),
+    reverse: probeReverse(config),
   }
 }
 
-/** 作业依赖：生效配置、命令执行面、作业完成后的现探刷新。 */
-export interface JobDeps {
-  config: AgentPresetReaConfig
-  runner: CommandRunner
-  refresh(): void
-}
-
 /**
  * 解析钉版在 registry 上的实际版本：顺带做存在性校验（失败即报错，
  * 而不是装出一棵空树让 MCP 行指向不存在的入口）。
@@ -413,6 +417,7 @@ export function createManager(options: {
       return {
         install: { phases: INSTALL_PHASES, run: (ctx) => runInstallJob(deps, ctx) },
         skill: { phases: SKILL_PHASES, run: (ctx) => runSkillJob(deps, ctx) },
+        reverse: { phases: REVERSE_PHASES, run: (ctx) => runReverseSkillJob(deps, ctx) },
       }
     },
   }

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
+  }
+}