dsh-plugin-showcase 0.0.0-stage → 0.2.0

package/lib/index.js

@@ -0,0 +1,664 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+export const name = 'showcase'
+export const inject = ['tools', 'commands']
+
+const VERSION = '0.2.0'
+const TOOL_NAME = 'showcase_inspect'
+const DOCTOR_TOOL_NAME = 'showcase_doctor'
+const COMMAND_NAME = 'showcase'
+const DENY_REASON = 'showcase: 拒绝执行破坏性命令'
+const USAGE = '/showcase [on|off|doctor|about]'
+const UNKNOWN = '未知'
+
+const LOCALE_NAMESPACE = 'locale'
+const LOCALE_FIELD = 'preference'
+const APP_BOOT_PACKAGE = '@deepseek-ai/dsh-app-boot'
+const STATUS_LABELS = Object.freeze({ ok: 'OK', warn: 'WARN', fail: 'FAIL', unknown: '?' })
+const HINT_FAULT = '这是 showcase 自身的缺陷：重跑 /showcase doctor，仍失败请到插件页反馈'
+
+const DESTRUCTIVE_PATTERNS = Object.freeze([
+  'rm -rf /',
+  'rm -rf ~',
+  ':(){:|:&;}',
+  ':(){ :|:& };:',
+  '.(){ :|:& };:',
+  'bomb(){ bomb|bomb& };bomb',
+  'del /f /s /q c:\\',
+  'format c:',
+])
+
+// Whitespace-removed twins: "rm  -rf  /", "FORMAT\tC:", and the collapsed fork-bomb spellings.
+const COMPACT_DESTRUCTIVE_PATTERNS = Object.freeze(
+  DESTRUCTIVE_PATTERNS.map(pattern => pattern.replace(/\s+/gu, '')),
+)
+
+const ELEVATION_PREFIXES = Object.freeze(['sudo', 'doas', 'pkexec'])
+const SHUTDOWN_WORD = /^shutdown(\.exe)?(\/(?:s|r|f)\w*)?$/u
+
+const COMMAND_ARG_KEYS = Object.freeze(['command', 'cmd', 'script', 'code'])
+
+function nullableString() {
+  return { oneOf: [{ type: 'string' }, { type: 'null' }] }
+}
+
+function buildSnapshotSchema() {
+  return {
+    type: 'object',
+    additionalProperties: false,
+    required: ['generatedAt', 'workspace', 'session', 'plugin', 'sections'],
+    properties: {
+      generatedAt: { type: 'string', description: 'ISO 8601 timestamp of this snapshot.' },
+      workspace: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['cwd', 'gitBranch'],
+        properties: {
+          cwd: { type: 'string', description: 'Effective working directory, empty when unknown.' },
+          gitBranch: { ...nullableString(), description: 'Checked-out git branch, null when not a repository.' },
+        },
+      },
+      session: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['id', 'model'],
+        properties: {
+          id: { ...nullableString(), description: 'Session identity of the last observed agent.' },
+          model: { ...nullableString(), description: 'Provider-qualified model id, null when unknown.' },
+        },
+      },
+      plugin: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['version', 'gateEnabled', 'toolName', 'command'],
+        properties: {
+          version: { type: 'string' },
+          gateEnabled: { type: 'boolean' },
+          toolName: { type: 'string' },
+          command: { type: 'string' },
+        },
+      },
+      sections: {
+        type: 'array',
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['title', 'items'],
+          properties: {
+            title: { type: 'string' },
+            items: {
+              type: 'array',
+              items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['label', 'value'],
+                properties: {
+                  label: { type: 'string' },
+                  value: { type: 'string' },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  }
+}
+
+function readService(ctx, key) {
+  try {
+    const service = ctx.get(key)
+    return service === null || typeof service !== 'object' ? null : service
+  } catch {
+    return null
+  }
+}
+
+function readAgentId(agent) {
+  try {
+    return agent !== null && typeof agent === 'object' && typeof agent.id === 'string' && agent.id !== ''
+      ? agent.id
+      : null
+  } catch {
+    return null
+  }
+}
+
+function readModel(ctx) {
+  const selection = readService(ctx, 'agentDefaultModel')
+  if (selection === null) return null
+  try {
+    const current = typeof selection.currentSelection === 'function' ? selection.currentSelection() : null
+    if (current === null || typeof current !== 'object') return null
+    const model = typeof current.model === 'string' ? current.model : ''
+    if (model === '') return null
+    const provider = typeof current.provider === 'string' ? current.provider : ''
+    return provider === '' ? model : provider + '/' + model
+  } catch {
+    return null
+  }
+}
+
+async function readCwd(ctx, agent) {
+  const directory = readService(ctx, 'workingDirectory')
+  if (directory === null) return ''
+  if (agent !== null) {
+    try {
+      const ensured = await directory.ensure(agent)
+      if (typeof ensured === 'string' && ensured !== '') return ensured
+    } catch {
+      /* fall through to the deployment fallback */
+    }
+  }
+  return typeof directory.defaultDirectory === 'string' ? directory.defaultDirectory : ''
+}
+
+async function readGitBranch(cwd) {
+  if (cwd === '') return null
+  try {
+    const head = (await readFile(join(cwd, '.git', 'HEAD'), 'utf8')).trim()
+    const match = /^ref:\s*refs\/heads\/(.+)$/u.exec(head)
+    if (match !== null && typeof match[1] === 'string' && match[1] !== '') return match[1]
+    return /^[0-9a-f]{7,40}$/u.test(head) ? head : null
+  } catch {
+    return null
+  }
+}
+
+function display(value) {
+  return value === null || value === '' ? UNKNOWN : value
+}
+
+function renderSnapshot(value) {
+  const snapshot = value !== null && typeof value === 'object' ? value : {}
+  const generatedAt = typeof snapshot.generatedAt === 'string' ? snapshot.generatedAt : ''
+  const lines = ['DSH 巡检报告 ' + generatedAt]
+  const sections = Array.isArray(snapshot.sections) ? snapshot.sections : []
+  for (const section of sections) {
+    if (section === null || typeof section !== 'object') continue
+    lines.push('## ' + (typeof section.title === 'string' ? section.title : UNKNOWN))
+    const items = Array.isArray(section.items) ? section.items : []
+    for (const item of items) {
+      if (item === null || typeof item !== 'object') continue
+      const label = typeof item.label === 'string' ? item.label : ''
+      const itemValue = typeof item.value === 'string' ? item.value : ''
+      lines.push('- ' + label + ': ' + itemValue)
+    }
+  }
+  return lines.join('\n')
+}
+
+async function buildSnapshot(ctx, state, agent) {
+  const id = readAgentId(agent)
+  const model = readModel(ctx)
+  if (id !== null) state.session.id = id
+  if (model !== null) state.session.model = model
+
+  const cwd = await readCwd(ctx, agent)
+  const gitBranch = await readGitBranch(cwd)
+  const sessionId = state.session.id
+  const sessionModel = state.session.model
+  const gate = state.gateEnabled
+
+  return {
+    generatedAt: new Date().toISOString(),
+    workspace: { cwd, gitBranch },
+    session: { id: sessionId, model: sessionModel },
+    plugin: { version: (await readOwnManifest()).version, gateEnabled: gate, toolName: TOOL_NAME, command: '/' + COMMAND_NAME },
+    sections: [
+      {
+        title: '工作区',
+        items: [
+          { label: '目录', value: display(cwd) },
+          { label: 'Git 分支', value: display(gitBranch) },
+        ],
+      },
+      {
+        title: '会话',
+        items: [
+          { label: '会话 ID', value: display(sessionId) },
+          { label: '模型', value: display(sessionModel) },
+        ],
+      },
+      {
+        title: '插件',
+        items: [
+          { label: '版本', value: (await readOwnManifest()).version },
+          { label: '拦截门', value: gate ? '开启' : '关闭' },
+          { label: '工具', value: TOOL_NAME },
+          { label: '命令', value: '/' + COMMAND_NAME },
+        ],
+      },
+    ],
+  }
+}
+
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+let ownManifestPromise = null
+
+async function loadOwnManifest() {
+  try {
+    const text = await readFile(new URL('../package.json', import.meta.url), 'utf8')
+    const parsed = JSON.parse(text)
+    const engines = parsed !== null && typeof parsed === 'object' && parsed.engines !== null && typeof parsed.engines === 'object'
+      ? parsed.engines
+      : {}
+    return {
+      version: typeof parsed.version === 'string' && parsed.version !== '' ? parsed.version : VERSION,
+      dshRange: typeof engines.dsh === 'string' && engines.dsh !== '' ? engines.dsh : null,
+    }
+  } catch {
+    return { version: VERSION, dshRange: null }
+  }
+}
+
+function readOwnManifest() {
+  if (ownManifestPromise === null) ownManifestPromise = loadOwnManifest()
+  return ownManifestPromise
+}
+
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u
+const COMPARATOR = /^(>=|<=|>|<|=|\^|~)?(\S+)$/u
+
+function parseSemver(text) {
+  const match = typeof text === 'string' ? SEMVER.exec(text.trim()) : null
+  if (match === null) return null
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    pre: match[4] === undefined ? [] : match[4].split('.'),
+  }
+}
+
+function compareIdentifier(left, right) {
+  const leftNumeric = /^\d+$/u.test(left)
+  const rightNumeric = /^\d+$/u.test(right)
+  if (leftNumeric && rightNumeric) return Number(left) - Number(right)
+  if (leftNumeric) return -1
+  if (rightNumeric) return 1
+  return left === right ? 0 : left < right ? -1 : 1
+}
+
+function compareSemver(left, right) {
+  for (const key of ['major', 'minor', 'patch']) {
+    if (left[key] !== right[key]) return left[key] - right[key]
+  }
+  if (left.pre.length === 0 && right.pre.length === 0) return 0
+  if (left.pre.length === 0) return 1
+  if (right.pre.length === 0) return -1
+  const length = Math.max(left.pre.length, right.pre.length)
+  for (let index = 0; index < length; index += 1) {
+    const leftPart = left.pre[index]
+    const rightPart = right.pre[index]
+    if (leftPart === undefined) return -1
+    if (rightPart === undefined) return 1
+    const delta = compareIdentifier(leftPart, rightPart)
+    if (delta !== 0) return delta
+  }
+  return 0
+}
+
+function upperBound(operator, target) {
+  if (operator === '^') {
+    if (target.major > 0) return { major: target.major + 1, minor: 0, patch: 0, pre: [] }
+    if (target.minor > 0) return { major: 0, minor: target.minor + 1, patch: 0, pre: [] }
+    return { major: 0, minor: 0, patch: target.patch + 1, pre: [] }
+  }
+  return { major: target.major, minor: target.minor + 1, patch: 0, pre: [] }
+}
+
+/** true/false when the range is a plain comparator set; null when it is not one this host can parse offline. */
+function satisfiesRange(version, range) {
+  const text = typeof range === 'string' ? range.trim() : ''
+  if (text === '' || text === '*' || text === 'x') return true
+  if (text.includes('||')) return null
+  for (const token of text.split(/\s+/u).filter(part => part !== '')) {
+    const match = COMPARATOR.exec(token)
+    if (match === null) return null
+    const operator = match[1] === undefined ? '=' : match[1]
+    const target = parseSemver(match[2])
+    if (target === null) return null
+    const delta = compareSemver(version, target)
+    if (operator === '>=' && delta < 0) return false
+    if (operator === '>' && delta <= 0) return false
+    if (operator === '<=' && delta > 0) return false
+    if (operator === '<' && delta >= 0) return false
+    if (operator === '=' && delta !== 0) return false
+    if (operator === '^' || operator === '~') {
+      if (delta < 0) return false
+      if (compareSemver(version, upperBound(operator, target)) >= 0) return false
+    }
+  }
+  return true
+}
+
+async function readDshVersion(ctx) {
+  const profile = readService(ctx, 'profileContext')
+  const dir = profile !== null && typeof profile.dir === 'string' && profile.dir !== '' ? profile.dir : null
+  if (dir === null) return null
+  try {
+    const parts = APP_BOOT_PACKAGE.split('/')
+    const text = await readFile(join(dir, 'node_modules', ...parts, 'package.json'), 'utf8')
+    const parsed = JSON.parse(text)
+    const version = parsed !== null && typeof parsed === 'object' ? parsed.version : undefined
+    return typeof version === 'string' && version !== '' ? version : null
+  } catch {
+    return null
+  }
+}
+
+function readLocale(ctx) {
+  const settings = readService(ctx, 'settings')
+  if (settings === null || typeof settings.describe !== 'function') return null
+  const descriptors = settings.describe()
+  if (!Array.isArray(descriptors)) return null
+  for (const descriptor of descriptors) {
+    if (descriptor === null || typeof descriptor !== 'object') continue
+    if (String(descriptor.ns) !== LOCALE_NAMESPACE) continue
+    const value = descriptor.value !== null && typeof descriptor.value === 'object' ? descriptor.value : {}
+    const preference = typeof value[LOCALE_FIELD] === 'string' ? value[LOCALE_FIELD] : ''
+    return preference === '' ? null : preference
+  }
+  return null
+}
+
+function readMarketIndexes(ctx) {
+  const market = readService(ctx, 'pluginMarket')
+  if (market === null || typeof market.listIndexes !== 'function') return { available: false, entries: [] }
+  const entries = market.listIndexes()
+  if (!Array.isArray(entries)) return { available: true, entries: [] }
+  return { available: true, entries: entries.filter(entry => entry !== null && typeof entry === 'object') }
+}
+
+function checkEngine(manifest, dshVersion) {
+  if (dshVersion === null) {
+    return {
+      status: 'unknown',
+      detail: '读不到 DSH 运行时版本',
+      hint: '需要 profileContext 服务，且 <profile>/node_modules/' + APP_BOOT_PACKAGE + '/package.json 可读',
+    }
+  }
+  const range = manifest.dshRange
+  if (range === null) {
+    return { status: 'warn', detail: '运行 ' + dshVersion + '，package.json 未声明 engines.dsh', hint: '补上 engines.dsh 后本项可比对兼容性' }
+  }
+  const parsed = parseSemver(dshVersion)
+  const satisfied = parsed === null ? null : satisfiesRange(parsed, range)
+  if (satisfied === null) {
+    return { status: 'unknown', detail: '运行 ' + dshVersion + '，要求 ' + range + '（范围写法无法离线解析）', hint: '该范围不是简单比较式，请人工确认兼容性' }
+  }
+  if (satisfied) return { status: 'ok', detail: '运行 ' + dshVersion + '，要求 ' + range, hint: null }
+  return { status: 'fail', detail: '运行 ' + dshVersion + '，要求 ' + range, hint: '升级 DSH，或改用与本机版本兼容的插件版本' }
+}
+
+function checkCwd(cwd) {
+  if (cwd === '') return { status: 'warn', detail: '读不到工作目录', hint: '需要 workingDirectory 服务，或本会话尚未选定目录' }
+  return { status: 'ok', detail: cwd, hint: null }
+}
+
+function checkModel(model) {
+  if (model === null) return { status: 'unknown', detail: '读不到默认模型', hint: '需要 agentDefaultModel 服务，或在设置里选定一次默认模型' }
+  return { status: 'ok', detail: model, hint: null }
+}
+
+function checkGate(gateEnabled) {
+  if (gateEnabled) return { status: 'ok', detail: '拦截门已开启', hint: null }
+  return { status: 'warn', detail: '拦截门已关闭', hint: '用 /showcase on 重新开启' }
+}
+
+function checkLocale(locale) {
+  if (locale === null) return { status: 'unknown', detail: '读不到宿主语言偏好', hint: '在设置里显式选择界面语言后，本项会显示 locale 偏好' }
+  return { status: 'ok', detail: locale, hint: null }
+}
+
+function checkMarket(market) {
+  if (!market.available) return { status: 'unknown', detail: '读不到市场索引服务 pluginMarket', hint: '该部署未挂载插件市场时本项可以忽略' }
+  if (market.entries.length === 0) return { status: 'warn', detail: '未配置市场索引源', hint: '在设置 → 插件市场里添加索引 URL' }
+  const describe = entry => (typeof entry.url === 'string' && entry.url !== '' ? entry.url : UNKNOWN)
+  const broken = market.entries.filter(entry => typeof entry.error === 'string' && entry.error !== '')
+  if (broken.length > 0) {
+    return {
+      status: 'warn',
+      detail: market.entries.length + ' 个索引源，' + broken.length + ' 个不可用: ' + broken.map(describe).join(', '),
+      hint: '修正或删除不可用的索引 URL',
+    }
+  }
+  return { status: 'ok', detail: market.entries.length + ' 个索引源: ' + market.entries.map(describe).join(', '), hint: null }
+}
+
+async function runCheck(id, title, produce) {
+  try {
+    const result = await produce()
+    if (result === null || typeof result !== 'object') {
+      return { id, title, status: 'unknown', detail: '检查未返回结果', hint: HINT_FAULT }
+    }
+    const status = STATUS_LABELS[result.status] === undefined ? 'unknown' : result.status
+    return {
+      id,
+      title,
+      status,
+      detail: typeof result.detail === 'string' ? result.detail : '',
+      hint: typeof result.hint === 'string' && result.hint !== '' ? result.hint : null,
+    }
+  } catch (error) {
+    return { id, title, status: 'unknown', detail: '检查异常: ' + messageOf(error), hint: HINT_FAULT }
+  }
+}
+
+function buildHealthSchema() {
+  return {
+    type: 'object',
+    additionalProperties: false,
+    required: ['generatedAt', 'pluginVersion', 'dshVersion', 'summary', 'checks'],
+    properties: {
+      generatedAt: { type: 'string', description: 'ISO 8601 timestamp of this report.' },
+      pluginVersion: { type: 'string' },
+      dshVersion: { ...nullableString(), description: 'Running DSH version, null when unreadable.' },
+      summary: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['ok', 'warn', 'fail', 'unknown'],
+        properties: {
+          ok: { type: 'integer' },
+          warn: { type: 'integer' },
+          fail: { type: 'integer' },
+          unknown: { type: 'integer' },
+        },
+      },
+      checks: {
+        type: 'array',
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['id', 'title', 'status', 'detail', 'hint'],
+          properties: {
+            id: { type: 'string' },
+            title: { type: 'string' },
+            status: { type: 'string', enum: ['ok', 'warn', 'fail', 'unknown'] },
+            detail: { type: 'string' },
+            hint: { ...nullableString(), description: 'Next step, null when there is none.' },
+          },
+        },
+      },
+    },
+  }
+}
+
+function renderHealth(value) {
+  const report = value !== null && typeof value === 'object' ? value : {}
+  const generatedAt = typeof report.generatedAt === 'string' ? report.generatedAt : ''
+  const lines = ['DSH 体检报告 ' + generatedAt]
+  const checks = Array.isArray(report.checks) ? report.checks : []
+  for (const check of checks) {
+    if (check === null || typeof check !== 'object') continue
+    const label = STATUS_LABELS[check.status] === undefined ? STATUS_LABELS.unknown : STATUS_LABELS[check.status]
+    const title = typeof check.title === 'string' ? check.title : UNKNOWN
+    const detail = typeof check.detail === 'string' ? check.detail : ''
+    lines.push('[' + label + '] ' + title + ' — ' + detail)
+    if (typeof check.hint === 'string' && check.hint !== '') lines.push('  ↳ ' + check.hint)
+  }
+  const summary = report.summary !== null && typeof report.summary === 'object' ? report.summary : {}
+  const count = key => (typeof summary[key] === 'number' ? summary[key] : 0)
+  lines.push('合计: ok ' + count('ok') + ' / warn ' + count('warn') + ' / fail ' + count('fail') + ' / unknown ' + count('unknown'))
+  return lines.join('\n')
+}
+
+async function buildHealthReport(ctx, state, agent) {
+  const manifest = await readOwnManifest()
+  const [dshVersion, cwd] = await Promise.all([readDshVersion(ctx), readCwd(ctx, agent)])
+  const model = readModel(ctx)
+  const checks = await Promise.all([
+    runCheck('engine.dsh', 'DSH 版本', () => checkEngine(manifest, dshVersion)),
+    runCheck('workspace.cwd', '工作目录', () => checkCwd(cwd)),
+    runCheck('model.default', '默认模型', () => checkModel(model)),
+    runCheck('plugin.gate', '拦截门', () => checkGate(state.gateEnabled)),
+    runCheck('plugin.locale', '界面语言', () => checkLocale(readLocale(ctx))),
+    runCheck('market.index', '市场索引', () => checkMarket(readMarketIndexes(ctx))),
+  ])
+  const summary = { ok: 0, warn: 0, fail: 0, unknown: 0 }
+  for (const check of checks) summary[check.status] += 1
+  return { generatedAt: new Date().toISOString(), pluginVersion: manifest.version, dshVersion, summary, checks }
+}
+
+async function aboutText(ctx, state) {
+  const manifest = await readOwnManifest()
+  const dshVersion = await readDshVersion(ctx)
+  return 'dsh-plugin-showcase ' + manifest.version
+    + ' · 工具 ' + TOOL_NAME + '、' + DOCTOR_TOOL_NAME
+    + ' · 命令 /' + COMMAND_NAME + ' on|off|doctor|about'
+    + ' · 拦截门' + (state.gateEnabled ? '已开启' : '已关闭')
+    + ' · DSH ' + (dshVersion === null ? UNKNOWN : dshVersion)
+}
+
+function collectCommandText(exec) {
+  const args = exec !== null && typeof exec === 'object' ? exec.arguments : null
+  if (args === null || typeof args !== 'object') return ''
+  const parts = []
+  for (const key of COMMAND_ARG_KEYS) {
+    if (!Object.hasOwn(args, key)) continue
+    const value = args[key]
+    if (typeof value === 'string') parts.push(value)
+    else if (Array.isArray(value)) {
+      for (const entry of value) {
+        if (typeof entry === 'string') parts.push(entry)
+      }
+    }
+  }
+  return parts.join('\n').toLowerCase()
+}
+
+// A shutdown only counts in command position: "echo shutdown" and
+// "npm run shutdown-check" are arguments, not a power action.
+function hasShutdownCommand(haystack) {
+  for (const segment of haystack.split(/[\n;&|]+/u)) {
+    const tokens = segment.split(/\s+/u).filter(token => token !== '')
+    let index = 0
+    while (index < tokens.length && ELEVATION_PREFIXES.includes(tokens[index])) index += 1
+    const word = tokens[index]
+    if (word !== undefined && SHUTDOWN_WORD.test(word)) return true
+  }
+  return false
+}
+
+function isDestructive(exec) {
+  const haystack = collectCommandText(exec)
+  if (haystack === '') return false
+  if (hasShutdownCommand(haystack)) return true
+  if (DESTRUCTIVE_PATTERNS.some(pattern => haystack.includes(pattern))) return true
+  const compact = haystack.replace(/\s+/gu, '')
+  return COMPACT_DESTRUCTIVE_PATTERNS.some(pattern => compact.includes(pattern))
+}
+
+async function runCommand(ctx, state, invocation) {
+  const raw = invocation !== null && typeof invocation === 'object' && typeof invocation.rawInput === 'string'
+    ? invocation.rawInput.trim().toLowerCase()
+    : ''
+  if (raw === 'on') {
+    state.gateEnabled = true
+    return { kind: 'success', text: 'showcase 拦截门: 已开启' }
+  }
+  if (raw === 'off') {
+    state.gateEnabled = false
+    return { kind: 'success', text: 'showcase 拦截门: 已关闭' }
+  }
+  const agent = invocation !== null && typeof invocation === 'object' ? invocation.agent ?? null : null
+  if (raw === 'doctor') return { kind: 'success', text: renderHealth(await buildHealthReport(ctx, state, agent)) }
+  if (raw === 'about') return { kind: 'success', text: await aboutText(ctx, state) }
+  if (raw !== '') return { kind: 'success', text: USAGE }
+  return { kind: 'success', text: renderSnapshot(await buildSnapshot(ctx, state, agent)) }
+}
+
+/** @param {import('@deepseek-ai/cordis').Context} ctx */
+export function apply(ctx) {
+  const state = { gateEnabled: true, session: { id: null, model: null } }
+
+  const inspectTool = {
+    name: TOOL_NAME,
+    description: 'Inspect this DSH host and return one snapshot: working directory, git branch, session identity, and the showcase plugin state.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {},
+      required: [],
+    },
+    output: {
+      schema: buildSnapshotSchema(),
+      render: (_args, value) => [{ type: 'text', text: renderSnapshot(value) }],
+    },
+    async execute(_args, exec) {
+      const agent = exec !== null && typeof exec === 'object' ? exec.agent ?? null : null
+      return await buildSnapshot(ctx, state, agent)
+    },
+  }
+
+  const doctorTool = {
+    name: DOCTOR_TOOL_NAME,
+    description: 'Run the DSH health check and return one report: engine version, working directory, default model, gate state, UI language, and market index sources.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {},
+      required: [],
+    },
+    output: {
+      schema: buildHealthSchema(),
+      render: (_args, value) => [{ type: 'text', text: renderHealth(value) }],
+    },
+    async execute(_args, exec) {
+      const agent = exec !== null && typeof exec === 'object' ? exec.agent ?? null : null
+      return await buildHealthReport(ctx, state, agent)
+    },
+  }
+
+  ctx.effect(() => ctx.tools.register(inspectTool), 'showcase: inspect tool')
+  ctx.effect(() => ctx.tools.register(doctorTool), 'showcase: doctor tool')
+
+  ctx.effect(() => ctx.on('tools/pre-execute', async (exec, next) => {
+    let decision = null
+    try {
+      if (state.gateEnabled && isDestructive(exec)) decision = { kind: 'deny', reason: DENY_REASON }
+    } catch {
+      /* a plugin fault must never block tool calls */
+      decision = null
+    }
+    return decision === null ? next() : decision
+  }), 'showcase: pre-execute gate')
+
+  ctx.effect(() => ctx.commands.register({
+    name: COMMAND_NAME,
+    description: 'Inspect this DSH host. Usage: /showcase [on|off|doctor|about]',
+    input: { hint: '[on|off|doctor|about]' },
+    handler: invocation => runCommand(ctx, state, invocation),
+  }), 'showcase: /showcase command')
+
+  ctx.provide('showcase', {
+    snapshot: () => buildSnapshot(ctx, state, null),
+    gateEnabled: () => state.gateEnabled,
+    setGateEnabled: enabled => { state.gateEnabled = enabled === true },
+  })
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Showcase",
+    "description": "DeepSeek Harness reference plugin: tools, hooks, commands, a settings card and a sidebar panel."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "功能展示",
+    "description": "DeepSeek Harness 参考插件：工具、钩子、命令、设置卡片与侧栏面板。"
+  }
+}