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

package/src/client/install.tsx

@@ -0,0 +1,373 @@
+/**
+ * 卡片的「REA 安装与更新」区：只读状态表 + 四个动作（安装/更新 REA、更新 REA skill、
+ * 更新 reverse-skill、取消作业）+ 运行中作业的阶段进度条、已用时与日志尾部。
+ *
+ * 状态与作业都来自宿主半的同源端点（见 client/api.ts 与宿主 routes.ts）：这里只管
+ * 轮询与呈现。作业在跑时按 {@link PROGRESS_POLL_MS} 轮询——进度是宿主侧的真事实，
+ * 浏览器不自己造百分比。
+ * @module agent-preset-rea/client/install
+ */
+import { Button } from '@dsh-plus/shared/client'
+import { type ReactElement, type ReactNode, useCallback, useEffect, useRef, useState } from 'react'
+
+import type { JobDto, ReverseSkillDto, SkillDto, StatusDto } from '../dto.ts'
+import { cancelJob, fetchStatus, startJob } from './api.ts'
+import type { Translate } from './i18n.ts'
+
+/** 作业运行中的状态轮询间隔（毫秒）。 */
+const PROGRESS_POLL_MS = 1000
+
+/** 日志展示尾部行数（宿主已按 200 行截断，这里再收一道以控高度）。 */
+const LOG_TAIL = 12
+
+/** 错误对象 → 人话。 */
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/** 起止时间 → 已用时文本。 */
+function elapsedOf(job: JobDto): string {
+  const start = Date.parse(job.startedAt)
+  if (Number.isNaN(start)) return '—'
+  const end = job.finishedAt === null ? Date.now() : Date.parse(job.finishedAt)
+  const seconds = Math.max(0, Math.round((end - start) / 1000))
+  if (seconds < 60) return `${seconds}s`
+  return `${Math.floor(seconds / 60)}m${String(seconds % 60).padStart(2, '0')}s`
+}
+
+/** 作业状态 → 徽标类名后缀（视觉区分运行中/成功/失败）。 */
+const STATE_CLASS = {
+  running: 'Running',
+  ok: 'Ok',
+  error: 'Error',
+  cancelled: 'Cancelled',
+} as const
+
+/** 作业种类 → 文案键。 */
+const JOB_LABEL = { install: 'jobInstall', skill: 'jobSkill', reverse: 'jobReverse' } as const
+
+/** 进度条百分比（防御性收窄，避免越界宽度）。 */
+function widthOf(percent: number): string {
+  return `${Math.max(0, Math.min(100, percent))}%`
+}
+
+/** 作业进度块：状态徽标 + 阶段 + 进度条 + 日志尾部。 */
+function JobPanel(props: { t: Translate; job: JobDto }): ReactElement {
+  const { t, job } = props
+  const stateKey =
+    job.state === 'running'
+      ? 'jobRunning'
+      : job.state === 'ok'
+        ? 'jobOk'
+        : job.state === 'error'
+          ? 'jobError'
+          : 'jobCancelled'
+  const lines = job.log.slice(-LOG_TAIL)
+  return (
+    <div className="apr-job">
+      <div className="apr-jobHead">
+        <span className={`apr-pill apr-pill${STATE_CLASS[job.state]}`}>{t(stateKey)}</span>
+        <span className="apr-jobTitle">{t(JOB_LABEL[job.kind])}</span>
+        <span className="apr-hint">
+          {t('jobPhase')} {job.progress.step}/{job.progress.steps}·{job.progress.phase}
+        </span>
+        <span className="apr-hint">
+          {t('jobElapsed')} {elapsedOf(job)}
+        </span>
+      </div>
+      <div
+        className="apr-bar"
+        role="progressbar"
+        aria-valuemin={0}
+        aria-valuemax={100}
+        aria-valuenow={job.progress.percent}
+      >
+        <div className="apr-barFill" style={{ width: widthOf(job.progress.percent) }} />
+      </div>
+      {job.error === null ? null : <p className="apr-error">{job.error}</p>}
+      <details className="apr-logBox" open={job.state !== 'ok'}>
+        <summary className="apr-logSummary">{t('jobLog')}</summary>
+        <pre className="apr-log">{lines.length === 0 ? t('jobLogEmpty') : lines.join('\n')}</pre>
+      </details>
+    </div>
+  )
+}
+
+/** 一行状态（键 + 值）。 */
+function StatusRow(props: { label: string; children: ReactNode }): ReactElement {
+  return (
+    <div className="apr-installRow">
+      <dt className="apr-installKey">{props.label}</dt>
+      <dd className="apr-installVal">{props.children}</dd>
+    </div>
+  )
+}
+
+/** 状态徽标（已就绪 / 未就绪 / 已关闭）。 */
+function Pill(props: { ok: boolean; label: string }): ReactElement {
+  return (
+    <span className={`apr-pill ${props.ok ? 'apr-pillOk' : 'apr-pillMiss'}`}>{props.label}</span>
+  )
+}
+
+/** REA 包与 MCP 行状态。 */
+function InstallRows(props: { t: Translate; status: StatusDto }): ReactElement {
+  const { t, status } = props
+  const mcpLabel = !status.mcp.enabled
+    ? status.config.mcpEnabled
+      ? t('mcpMissing')
+      : t('mcpOff')
+    : status.mcp.mode === 'custom'
+      ? t('mcpCustom')
+      : t('mcpInstalled')
+  return (
+    <>
+      <StatusRow label={t('installPackage')}>
+        <Pill
+          ok={status.install.installed}
+          label={t(status.install.installed ? 'installed' : 'notInstalled')}
+        />
+        {status.install.version === null ? null : (
+          <span className="apr-mono">{status.install.version}</span>
+        )}
+        <span className="apr-hint">
+          {t('installTarget')} {status.config.reaVersion}
+        </span>
+      </StatusRow>
+      <StatusRow label={t('installPath')}>
+        <code className="apr-mono">{status.install.root}</code>
+      </StatusRow>
+      <StatusRow label={t('mcpRow')}>
+        <span className="apr-mono">{mcpLabel}</span>
+        {status.mcp.command === null ? null : (
+          <code className="apr-mono">
+            {status.mcp.command} {status.mcp.args.join(' ')}
+          </code>
+        )}
+      </StatusRow>
+    </>
+  )
+}
+
+/** REA 官方 skill 状态。 */
+function SkillRows(props: { t: Translate; skill: SkillDto; enabled: boolean }): ReactElement {
+  const { t, skill, enabled } = props
+  const version = skill.version === null ? '' : ` · ${skill.version}`
+  return (
+    <StatusRow label={t('skillSource')}>
+      <Pill ok={enabled} label={t(enabled ? 'enabled' : 'disabled')} />
+      <span className="apr-mono">
+        {t(skill.source === 'updated' ? 'skillUpdated' : 'skillBundled')}
+      </span>
+      <span className="apr-hint">
+        {t('skillFiles')} {skill.files}
+        {version}
+      </span>
+      {skill.updatedAt === null ? null : (
+        <span className="apr-hint">
+          {t('updatedAt')} {skill.updatedAt}
+        </span>
+      )}
+    </StatusRow>
+  )
+}
+
+/** reverse-skill（GitHub 源）状态。 */
+function ReverseRows(props: {
+  t: Translate
+  reverse: ReverseSkillDto
+  enabled: boolean
+}): ReactElement {
+  const { t, reverse, enabled } = props
+  const active = reverse.activeGroups.length === 0 ? '—' : reverse.activeGroups.join(', ')
+  const all = reverse.groups.length === 0 ? '—' : reverse.groups.join(', ')
+  return (
+    <>
+      <StatusRow label={t('reverseSource')}>
+        <Pill ok={reverse.installed} label={t(reverse.installed ? 'installed' : 'notInstalled')} />
+        <span className="apr-mono">{reverse.repo}</span>
+        {reverse.sha === null ? null : (
+          <span className="apr-hint">
+            {t('reverseCommit')} {reverse.sha.slice(0, 12)}
+            {reverse.version === null ? '' : ` · v${reverse.version}`}
+          </span>
+        )}
+      </StatusRow>
+      <StatusRow label={t('reverseGroups')}>
+        <Pill ok={enabled} label={t(enabled ? 'enabled' : 'disabled')} />
+        <span className="apr-mono">{active}</span>
+        <span className="apr-hint">
+          {t('reverseGroupsHint')} {all}
+        </span>
+      </StatusRow>
+      <StatusRow label={t('reversePath')}>
+        <code className="apr-mono">{reverse.tree}</code>
+        {reverse.updatedAt === null ? null : (
+          <span className="apr-hint">
+            {t('updatedAt')} {reverse.updatedAt}
+          </span>
+        )}
+      </StatusRow>
+    </>
+  )
+}
+
+/** 只读状态表：REA 包 / MCP 行 / REA skill / reverse-skill。 */
+function StatusTable(props: { t: Translate; status: StatusDto }): ReactElement {
+  const { t, status } = props
+  return (
+    <dl className="apr-install">
+      <InstallRows t={t} status={status} />
+      <SkillRows t={t} skill={status.skill} enabled={status.config.skillEnabled} />
+      <ReverseRows t={t} reverse={status.reverse} enabled={status.config.reverseSkillEnabled} />
+    </dl>
+  )
+}
+
+/** 动作按钮行。 */
+function ActionRow(props: {
+  t: Translate
+  busy: boolean
+  running: boolean
+  disabled: boolean
+  proxyPort: number | null
+  onAction(kind: 'install' | 'skill' | 'reverse'): void
+  onCancel(): void
+}): ReactElement {
+  const { t, busy, running, disabled, proxyPort, onAction, onCancel } = props
+  const blocked = disabled || busy || running || proxyPort === null
+  return (
+    <div className="apr-btnRow">
+      <Button
+        prefix="apr"
+        variant="primary"
+        label={t('installAction')}
+        disabled={blocked}
+        onClick={() => onAction('install')}
+      />
+      <Button
+        prefix="apr"
+        label={t('skillAction')}
+        disabled={blocked}
+        onClick={() => onAction('skill')}
+      />
+      <Button
+        prefix="apr"
+        label={t('reverseAction')}
+        disabled={blocked}
+        onClick={() => onAction('reverse')}
+      />
+      {running ? (
+        <Button prefix="apr" label={t('cancelAction')} disabled={busy} onClick={onCancel} />
+      ) : null}
+    </div>
+  )
+}
+
+export interface InstallSectionProps {
+  t: Translate
+  /** 设置只读（不可写）时禁用全部动作。 */
+  disabled: boolean
+  /** 草稿里的代理端口（非法为 null → 禁用动作，不静默取 0）。 */
+  proxyPort: number | null
+}
+
+export function InstallSection(props: InstallSectionProps): ReactElement {
+  const { t, disabled, proxyPort } = props
+  const [status, setStatus] = useState<StatusDto | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [busy, setBusy] = useState(false)
+  const alive = useRef(true)
+  useEffect(
+    () => () => {
+      alive.current = false
+    },
+    [],
+  )
+
+  const load = useCallback(async (): Promise<void> => {
+    try {
+      const next = await fetchStatus()
+      if (!alive.current) return
+      setStatus(next)
+      setError(null)
+    } catch (failure) {
+      if (alive.current) setError(`${t('statusFailed')}${messageOf(failure)}`)
+    }
+  }, [t])
+
+  useEffect(() => {
+    void load()
+  }, [load])
+
+  const running = status?.job?.state === 'running'
+  useEffect(() => {
+    if (running !== true) return
+    const timer = window.setInterval(() => {
+      void load()
+    }, PROGRESS_POLL_MS)
+    return () => {
+      window.clearInterval(timer)
+    }
+  }, [running, load])
+
+  const runAction = useCallback(
+    (action: () => Promise<{ job: JobDto | null }>): void => {
+      setBusy(true)
+      setError(null)
+      action()
+        .then((result) => {
+          if (!alive.current) return
+          setStatus((prev) => (prev === null ? prev : { ...prev, job: result.job }))
+          void load()
+        })
+        .catch((failure: unknown) => {
+          if (alive.current) setError(`${t('actionFailed')}${messageOf(failure)}`)
+        })
+        .finally(() => {
+          if (alive.current) setBusy(false)
+        })
+    },
+    [load, t],
+  )
+
+  const job = status?.job ?? null
+  return (
+    <section className="apr-field">
+      <div className="apr-head">
+        <span className="apr-label">{t('installSection')}</span>
+        <Button
+          prefix="apr"
+          label={t('refreshStatus')}
+          disabled={busy || running === true}
+          onClick={() => {
+            void load()
+          }}
+        />
+      </div>
+      {status === null ? (
+        <p className="apr-hint">{t('statusLoading')}</p>
+      ) : (
+        <>
+          <StatusTable t={t} status={status} />
+          <ActionRow
+            t={t}
+            busy={busy}
+            running={running === true}
+            disabled={disabled}
+            proxyPort={proxyPort}
+            onAction={(kind) => {
+              runAction(() => startJob(kind, proxyPort ?? 0))
+            }}
+            onCancel={() => {
+              runAction(() => cancelJob())
+            }}
+          />
+        </>
+      )}
+      {job === null ? null : <JobPanel t={t} job={job} />}
+      {error === null ? null : <p className="apr-error">{error}</p>}
+      <p className="apr-hint">{t('installHint')}</p>
+    </section>
+  )
+}

package/src/client/styles.ts

@@ -1,7 +1,9 @@
 /**
- * 配置卡片样式：基础规则走 @dsh-plus/shared/client 的 cardCss('apr')，
- * 本文件只补插件特有规则（提示词多行输入框）。
+ * 配置卡片样式：基础规则走 @dsh-plus/shared/client 的 cardCss('apr')
+ * （按钮/字段/徽标等类名由共享控件生成，本文件**不**重复定义），这里只补
+ * 插件特有规则：提示词多行框、安装状态表、作业进度条与日志。
  * 沿用官方 data-plugin / data-plugin-css 约定（HMR 据此卸载）。
+ * 颜色与度量全部走官方主题变量（--dsw-alias-*），不写死色值。
  * @module agent-preset-rea/client/styles
  */
 import { cardCss, injectCardStyle } from '@dsh-plus/shared/client'
@@ -12,6 +14,9 @@ export const PLUGIN_ID = '@dsh-plus/agent-preset-rea'
  * 多行提示词输入框：度量对齐官方 settings-form 的 textarea
  * （与 -input 同边框/底色/圆角，正文 13px/1.6），窄屏 16px 防 iOS 聚焦缩放、
  * 纵向可拖拽但不横向溢出。
+ *
+ * 类名避让 cardCss 已生成的 `-status` / `-badge` 前缀（那是 CardChrome 的状态行与
+ * 字段徽标），安装表与作业块一律用 `-install*` / `-pill*` / `-job*`。
  */
 const extraCss = `
 .apr-textarea{box-sizing:border-box;width:100%;min-height:180px;resize:vertical;font:inherit;font-size:13px;line-height:1.6;color:var(--dsw-alias-label-primary);background:var(--dsw-alias-bg-layer-3);border:1px solid var(--dsw-alias-border-l2);border-radius:8px;padding:10px 12px;transition:border-color .18s,background .18s}
@@ -19,8 +24,28 @@ const extraCss = `
 .apr-textarea:focus-visible{border-color:var(--dsw-alias-brand-primary);outline:none}
 .apr-textarea:disabled{color:var(--dsw-alias-label-tertiary);cursor:default}
 .apr-textarea::placeholder{color:var(--dsw-alias-label-tertiary)}
+.apr-btnRow{display:flex;flex-wrap:wrap;gap:8px;margin-top:10px}
+.apr-install{margin:6px 0 0;padding:0;display:flex;flex-direction:column;gap:6px}
+.apr-installRow{display:flex;gap:10px;align-items:baseline;flex-wrap:wrap}
+.apr-installKey{flex:none;width:118px;margin:0;font-size:12px;color:var(--dsw-alias-label-tertiary)}
+.apr-installVal{display:flex;gap:8px;align-items:center;flex-wrap:wrap;margin:0;font-size:13px;color:var(--dsw-alias-label-primary)}
+.apr-mono{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:12px;word-break:break-all}
+.apr-pill{flex:none;padding:2px 8px;border-radius:999px;font-size:11px;line-height:16px}
+.apr-pillOk{background:var(--dsw-alias-state-success-secondary);color:var(--dsw-alias-state-success-primary)}
+.apr-pillMiss,.apr-pillError,.apr-pillCancelled{background:var(--dsw-alias-state-error-secondary);color:var(--dsw-alias-state-error-primary)}
+.apr-pillRunning{background:var(--dsw-alias-interactive-bg-hover);color:var(--dsw-alias-label-primary)}
+.apr-job{margin-top:12px;padding:10px 12px;border:1px solid var(--dsw-alias-border-l2);border-radius:8px;background:var(--dsw-alias-bg-layer-3)}
+.apr-jobHead{display:flex;align-items:center;gap:8px;flex-wrap:wrap}
+.apr-jobTitle{font-size:13px;font-weight:500;color:var(--dsw-alias-label-primary)}
+.apr-bar{margin-top:8px;height:6px;border-radius:999px;background:var(--dsw-alias-interactive-bg-hover);overflow:hidden}
+.apr-barFill{height:100%;background:var(--dsw-alias-brand-primary);transition:width .3s}
+.apr-logBox{margin-top:8px}
+.apr-logSummary{font-size:12px;color:var(--dsw-alias-label-tertiary);cursor:pointer}
+.apr-log{margin:6px 0 0;max-height:200px;overflow:auto;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:11px;line-height:1.5;white-space:pre-wrap;word-break:break-all;color:var(--dsw-alias-label-tertiary)}
+.apr-error{margin:4px 0 0;font-size:12px;color:var(--dsw-alias-state-error-primary)}
 @media (max-width:767px){
 .apr-textarea{font-size:16px;min-height:140px}
+.apr-installKey{width:100%}
 }
 `
 

package/src/client/toggles.tsx

@@ -0,0 +1,57 @@
+/**
+ * 卡片的「能力开关」区：三个一键开关（REA MCP 行 / REA 官方 skill / reverse-skill
+ * 技能包）。三者都是活动字段，保存后本预设换代注册——新建会话按新装配起（REA 工具
+ * 与 skill 根的有无），已存在会话保持既有装配。
+ *
+ * 开关只管「挂不挂」，不管「装没装」：关掉不会删磁盘上的安装副本（更新/回滚仍是
+ * 显式动作，见 install.tsx）。
+ * @module agent-preset-rea/client/toggles
+ */
+import { CheckRow } from '@dsh-plus/shared/client'
+import type { ReactElement } from 'react'
+
+import type { Draft } from './draft.ts'
+import type { Translate } from './i18n.ts'
+
+/** 三个开关的键与文案键。 */
+const TOGGLES = [
+  { field: 'mcpEnabled', id: 'apr-toggle-mcp', label: 'toggleMcp', hint: 'toggleMcpHint' },
+  { field: 'skillEnabled', id: 'apr-toggle-skill', label: 'toggleSkill', hint: 'toggleSkillHint' },
+  {
+    field: 'reverseSkillEnabled',
+    id: 'apr-toggle-reverse',
+    label: 'toggleReverse',
+    hint: 'toggleReverseHint',
+  },
+] as const
+
+export interface ToggleSectionProps {
+  t: Translate
+  draft: Draft
+  disabled: boolean
+  onEdit(patch: Partial<Draft>): void
+}
+
+export function ToggleSection(props: ToggleSectionProps): ReactElement {
+  const { t, draft, disabled, onEdit } = props
+  return (
+    <section className="apr-field">
+      <div className="apr-head">
+        <span className="apr-label">{t('toggleSection')}</span>
+      </div>
+      {TOGGLES.map((toggle) => (
+        <div key={toggle.field}>
+          <CheckRow
+            prefix="apr"
+            id={toggle.id}
+            label={t(toggle.label)}
+            checked={draft[toggle.field]}
+            disabled={disabled}
+            onEdit={(checked) => onEdit({ [toggle.field]: checked })}
+          />
+          <p className="apr-hint">{t(toggle.hint)}</p>
+        </div>
+      ))}
+    </section>
+  )
+}

package/src/config.ts

@@ -5,10 +5,11 @@
  * 与 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 身份、工具指引、项目指令、
@@ -21,12 +22,7 @@
 import z from '@deepseek-ai/schemastery'
 import type { UnwrapVolatile } from '@dsh-plus/shared'
 
-import {
-  DEFAULT_MCP_COMMAND,
-  INPUT_SCHEMA_PROFILES,
-  OUTPUT_SCHEMA_PROFILES,
-  REA_PINNED_VERSION,
-} from './mcp.ts'
+import { INPUT_SCHEMA_PROFILES, OUTPUT_SCHEMA_PROFILES, REA_PINNED_VERSION } from './mcp.ts'
 import { SETTINGS_NS as NS_LITERAL } from './ns.ts'
 
 /** settings 命名空间（字面量即合法命名空间；配置卡片与运行期读取同一份）。 */
@@ -55,7 +51,35 @@ export const Config = z.object({
   mcpEnabled: z
     .boolean()
     .description('是否挂 REA MCP 客户端行（false = 只保留预设其余能力）')
-    .default(true),
+    .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}$/)
@@ -67,13 +91,29 @@ export const Config = z.object({
     .string()
     .description('钉版的 rea-agents 版本（npx 拉取）')
     .default(REA_PINNED_VERSION),
+  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 stdio 可执行文件；Windows 需 cmd.exe 配方，见包文档')
-    .default(DEFAULT_MCP_COMMAND),
+    .description(
+      '显式 MCP 启动命令（空 = 用受管安装入口，未安装时该行禁用；填 npx 即启动期拉取，风险自负）',
+    )
+    .default(''),
   mcpArgs: z
     .array(z.string())
-    .description('MCP stdio 参数；留空 = 按 reaVersion 派生 ["-y","rea-agents@<version>","mcp"]')
+    .description(
+      'MCP stdio 附加参数；留空 = 受管入口补 ["mcp"]，显式 npx 则派生 ["-y","rea-agents@<version>","mcp"]',
+    )
     .default([]),
   inputSchemaProfile: z
     .union(INPUT_SCHEMA_PROFILES)