dsh-plugin-capabilities 0.3.6 → 0.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-capabilities",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Manage skills and MCP servers from the Web UI Settings. 在设置页管理 dsh 的技能与 MCP 服务器。",
   "type": "module",
   "main": "lib/index.js",

package/src/client/MarketTab.tsx

@@ -114,7 +114,7 @@ export function MarketTab(props: { t: Translate; market: MarketInjected; mcp: Mc
         setOutcome({ ok: true, text: t('rootRemoved') })
         refreshSkills()
       } else {
-        await mcp.remove(target.id)
+        await mcp.remove(target.id, 'profile')
         setOutcome({ ok: true, text: t('restartNeeded') })
         refreshMcp()
       }

package/src/client/McpTab.tsx

@@ -1,6 +1,7 @@
-/** Settings → Plugins “MCP” tab: manage the profile's mcp-client rows.
- * Mutations rewrite the profile patch and need a dsh restart — the banner
- * hands the restart to the desktop shell when one is present. */
+/** Settings → Plugins “MCP” tab: manage the mcp-client rows in both patch
+ * layers (profile + global). Mutations rewrite the target patch and need a
+ * dsh restart — the banner hands the restart to the desktop shell when one
+ * is present. */
 
 import { useEffect, useState } from 'react'
 import type { ReactElement } from 'react'
@@ -8,11 +9,17 @@ import { Button, IconApiOutline14, IconRefreshOutline14, Modal, StateDot } from
 import { CSS } from './css.ts'
 import type { ImportedServerView, Translate } from './index.ts'
 
+/** Which patch layer a row lives in. */
+export type McpScope = 'global' | 'profile'
+
 export interface McpRow {
   id: string
   serverName: string
   transport: 'stdio' | 'streamable-http'
   disabled: boolean
+  scope: McpScope
+  /** Profile rows only: a global row with the same id composes after this one and wins. */
+  shadowed?: boolean
   command?: string
   args?: string[]
   env?: Record<string, string>
@@ -22,10 +29,10 @@ export interface McpRow {
 }
 
 export interface McpInjected {
-  list(): Promise<{ servers: McpRow[] }>
+  list(): Promise<{ servers: McpRow[]; globalError?: string }>
   save(input: Record<string, unknown>): Promise<{ ok: boolean; id: string }>
-  toggle(id: string, disabled: boolean): Promise<{ ok: boolean }>
-  remove(id: string): Promise<{ ok: boolean }>
+  toggle(id: string, disabled: boolean, scope: McpScope): Promise<{ ok: boolean }>
+  remove(id: string, scope: McpScope): Promise<{ ok: boolean }>
   scanImport(): Promise<{ servers: ImportedServerView[]; existing: string[] }>
   applyImport(items: Array<{ agent: string; name: string }>): Promise<{ ok: boolean; results: Array<{ name: string; ok: boolean; error?: string }> }>
   restart(): Promise<void>
@@ -35,6 +42,8 @@ export interface McpInjected {
 /** Editor dialog state; null when closed. Textareas hold line-based values. */
 interface EditorState {
   id: string
+  /** Fixed after create: a row is edited in the layer that holds it. */
+  scope: McpScope
   serverName: string
   transport: 'stdio' | 'streamable-http'
   command: string
@@ -208,7 +217,8 @@ export function McpTab(props: { t: Translate; injected: McpInjected }): ReactEle
   const { t, injected } = props
   const [servers, setServers] = useState<McpRow[] | null>(null)
   const [editor, setEditor] = useState<EditorState | null>(null)
-  const [confirmId, setConfirmId] = useState<string | null>(null)
+  const [confirmRow, setConfirmRow] = useState<McpRow | null>(null)
+  const [globalError, setGlobalError] = useState<string | null>(null)
   const [importOpen, setImportOpen] = useState(false)
   const [importItems, setImportItems] = useState<Array<{ server: ImportedServerView; existing: boolean; checked: boolean }> | null>(null)
   const [busy, setBusy] = useState(false)
@@ -266,7 +276,11 @@ export function McpTab(props: { t: Translate; injected: McpInjected }): ReactEle
   useEffect(() => {
     let current = true
     void injected.list().then(
-      (body) => { if (current) setServers(body.servers) },
+      (body) => {
+        if (!current) return
+        setServers(body.servers)
+        setGlobalError(body.globalError ?? null)
+      },
       (error: Error) => { if (current) { setServers([]); setOutcome({ ok: false, text: `${t('failed')}: ${String(error.message ?? error)}` }) } },
     )
     return () => { current = false }
@@ -276,7 +290,7 @@ export function McpTab(props: { t: Translate; injected: McpInjected }): ReactEle
     setFormError(null)
     setPasteError(null)
     setPasteJson('')
-    setEditor({ id: '', serverName: '', transport: 'stdio', command: '', args: '', env: '', url: '', headers: '' })
+    setEditor({ id: '', scope: 'profile', serverName: '', transport: 'stdio', command: '', args: '', env: '', url: '', headers: '' })
   }
 
   const openEdit = (row: McpRow): void => {
@@ -285,6 +299,7 @@ export function McpTab(props: { t: Translate; injected: McpInjected }): ReactEle
     setPasteJson('')
     setEditor({
       id: row.id,
+      scope: row.scope,
       serverName: row.serverName,
       transport: row.transport,
       command: row.command ?? '',
@@ -336,6 +351,7 @@ export function McpTab(props: { t: Translate; injected: McpInjected }): ReactEle
     try {
       await injected.save({
         id: editor.id,
+        scope: editor.scope,
         serverName: editor.serverName.trim(),
         transport: editor.transport,
         ...(editor.transport === 'stdio'
@@ -362,7 +378,7 @@ export function McpTab(props: { t: Translate; injected: McpInjected }): ReactEle
   const doToggle = async (row: McpRow): Promise<void> => {
     setBusy(true)
     try {
-      await injected.toggle(row.id, !row.disabled)
+      await injected.toggle(row.id, !row.disabled, row.scope)
       setOutcome({ ok: true, text: t('restartNeeded') })
       reloadList(true)
     } catch (error) {
@@ -373,17 +389,17 @@ export function McpTab(props: { t: Translate; injected: McpInjected }): ReactEle
   }
 
   const doRemove = async (): Promise<void> => {
-    if (confirmId === null) return
+    if (confirmRow === null) return
     setBusy(true)
     try {
-      await injected.remove(confirmId)
+      await injected.remove(confirmRow.id, confirmRow.scope)
       setOutcome({ ok: true, text: t('restartNeeded') })
       reloadList(true)
     } catch (error) {
       setOutcome({ ok: false, text: `${t('failed')}: ${String(error instanceof Error ? error.message : error)}` })
     } finally {
       setBusy(false)
-      setConfirmId(null)
+      setConfirmRow(null)
     }
   }
 
@@ -442,6 +458,15 @@ export function McpTab(props: { t: Translate; injected: McpInjected }): ReactEle
           <div className="dpc-bannerBody"><span>{outcome.text}</span></div>
         </div>
       )}
+      {globalError !== null && (
+        <div className="dpc-banner" data-kind="error" role="alert">
+          <StateDot state="error" size={10} />
+          <div className="dpc-bannerBody">
+            <span>{t('globalLayerError')}</span>
+            <span className="dpc-bannerHint">{globalError}</span>
+          </div>
+        </div>
+      )}
       {(pending || restarting) && restartBanner}
 
       <div className="dpc-listHead">
@@ -458,20 +483,22 @@ export function McpTab(props: { t: Translate; injected: McpInjected }): ReactEle
       {servers !== null && servers.length > 0 && (
         <ul className="dpc-cards">
           {servers.map((row) => (
-            <li className="dpc-card" key={row.id}>
+            <li className="dpc-card" key={`${row.scope}/${row.id}`}>
               <div className="dpc-cardTop">
                 <strong className="dpc-cardTitle" title={row.id}>{row.serverName}</strong>
+                <span className="dpc-tag" data-kind={row.scope === 'global' ? 'source' : undefined}>{row.scope === 'global' ? t('scopeGlobal') : t('scopeProfile')}</span>
                 <span className="dpc-tag">{row.transport}</span>
                 <span className="dpc-tag" data-kind={row.disabled ? 'off' : undefined}>{row.disabled ? t('disabled') : t('enabled')}</span>
               </div>
               <p className="dpc-cardDesc">
                 {row.transport === 'stdio' ? `${row.command ?? ''} ${(row.args ?? []).join(' ')}` : row.url ?? ''}
               </p>
+              {row.shadowed === true && <p className="dpc-formError">{t('shadowedByGlobal')}</p>}
               <div className="dpc-cardRow">
                 <span className="dpc-spacer" />
                 <Button variant="ghost" size="sm" disabled={busy} onClick={() => void doToggle(row)}>{t('toggle')}</Button>
                 <Button variant="ghost" size="sm" disabled={busy} onClick={() => openEdit(row)}>{t('edit')}</Button>
-                <Button variant="ghost" size="sm" disabled={busy} onClick={() => setConfirmId(row.id)}>{t('delete')}</Button>
+                <Button variant="ghost" size="sm" disabled={busy} onClick={() => setConfirmRow(row)}>{t('delete')}</Button>
               </div>
             </li>
           ))}
@@ -487,6 +514,19 @@ export function McpTab(props: { t: Translate; injected: McpInjected }): ReactEle
       >
         {editor !== null && (
           <div className="dpc-form">
+            <label className="dpc-label">
+              <span>{t('scopeLabel')}</span>
+              <select
+                className="dpc-select"
+                value={editor.scope}
+                disabled={editor.id !== ''}
+                onChange={(event) => setEditor({ ...editor, scope: event.target.value as McpScope })}
+              >
+                <option value="profile">{t('scopeProfile')}</option>
+                <option value="global">{t('scopeGlobal')}</option>
+              </select>
+              <span className="dpc-formatHint">{t('scopeHint')}</span>
+            </label>
             <label className="dpc-label">
               <span>{t('serverName')}</span>
               <input
@@ -582,13 +622,13 @@ export function McpTab(props: { t: Translate; injected: McpInjected }): ReactEle
       </Modal>
 
       <Modal
-        open={confirmId !== null}
-        onClose={() => setConfirmId(null)}
+        open={confirmRow !== null}
+        onClose={() => setConfirmRow(null)}
         title={t('confirmRemove')}
-        description={confirmId ?? undefined}
+        description={confirmRow?.serverName ?? undefined}
         footer={
           <>
-            <Button variant="ghost" onClick={() => setConfirmId(null)}>{t('cancel')}</Button>
+            <Button variant="ghost" onClick={() => setConfirmRow(null)}>{t('cancel')}</Button>
             <Button variant="primary" disabled={busy} onClick={() => void doRemove()}>{t('delete')}</Button>
           </>
         }

package/src/client/index.ts

@@ -4,7 +4,7 @@
 
 import { createElement as h } from 'react'
 import { CapabilitiesSection } from './CapabilitiesSection.tsx'
-import type { McpInjected, McpRow } from './McpTab.tsx'
+import type { McpInjected, McpRow, McpScope } from './McpTab.tsx'
 import type { MarketInjected, RootRowView } from './MarketTab.tsx'
 import type { SkillsInjected, SkillRowView } from './SkillsTab.tsx'
 import { zh, en } from './locales.ts'
@@ -89,10 +89,11 @@ export function apply(ctx: CapabilitiesClientContext): void {
   }
 
   const mcpInjected: McpInjected = {
-    list: () => fetchJson<{ servers: McpRow[] }>('/dsh-plugin-capabilities/mcp'),
+    list: () => fetchJson<{ servers: McpRow[]; globalError?: string }>('/dsh-plugin-capabilities/mcp'),
     save: (input: unknown) => post('/dsh-plugin-capabilities/mcp/save', input) as Promise<{ ok: boolean; id: string }>,
-    toggle: (id: string, disabled: boolean) => post('/dsh-plugin-capabilities/mcp/toggle', { id, disabled }) as Promise<{ ok: boolean }>,
-    remove: (id: string) => post('/dsh-plugin-capabilities/mcp/remove', { id }) as Promise<{ ok: boolean }>,
+    toggle: (id: string, disabled: boolean, scope: McpScope) =>
+      post('/dsh-plugin-capabilities/mcp/toggle', { id, disabled, scope }) as Promise<{ ok: boolean }>,
+    remove: (id: string, scope: McpScope) => post('/dsh-plugin-capabilities/mcp/remove', { id, scope }) as Promise<{ ok: boolean }>,
     scanImport: () => fetchJson<{ servers: ImportedServerView[]; existing: string[] }>('/dsh-plugin-capabilities/import/scan'),
     applyImport: (items: Array<{ agent: string; name: string }>) =>
       post('/dsh-plugin-capabilities/import/apply', { items }) as Promise<{ ok: boolean; results: Array<{ name: string; ok: boolean; error?: string }> }>,

package/src/client/locales.ts

@@ -68,9 +68,15 @@ export const zh = {
   confirmRemoveRoot: '确认移除该仓库？',
   removeRootWarn: '将取消扫描该仓库并删除下载到 DSH_HOME 的副本（本地目录本身不受影响）。',
   mcpTitle: 'MCP 服务器',
-  mcpIntro: '管理 profile 中的 MCP 服务器行（@deepseek-ai/dsh-mcp-client）。新增、修改或删除后需要重启 dsh 才生效。',
+  mcpIntro: '管理 MCP 服务器行（@deepseek-ai/dsh-mcp-client）。服务器可放在 profile 层（仅本 profile）或全局层（DSH_HOME/cordis.patch.yml，对本机所有 profile 生效）；新增、修改或删除后需要重启 dsh 才生效。',
   addServer: '添加服务器',
   editServer: '编辑服务器',
+  scopeLabel: '生效范围',
+  scopeGlobal: '全局',
+  scopeProfile: '当前 profile',
+  scopeHint: '全局：写入 DSH_HOME/cordis.patch.yml，对本机所有 profile 生效；当前 profile：只影响本 profile。',
+  shadowedByGlobal: '全局层存在同名 id，此行不生效',
+  globalLayerError: '全局配置（DSH_HOME/cordis.patch.yml）读取失败，全局服务器暂未显示：',
   serverName: '服务器名（工具名前缀）',
   transport: '传输方式',
   transportStdio: 'stdio（本地命令）',
@@ -84,7 +90,7 @@ export const zh = {
   enabled: '启用中',
   toggle: '停用/启用',
   confirmRemove: '确认移除该服务器？',
-  removeWarn: '将从 profile 配置中移除这一行，重启 dsh 后其工具不再出现。',
+  removeWarn: '将从配置中移除这一行，重启 dsh 后其工具不再出现。',
   emptyMcp: '还没有配置 MCP 服务器',
   importServers: '从其他 Agent 导入',
   importIntro: '扫描 Claude Code（~/.claude.json）与 Codex（~/.codex/config.toml）的 MCP 服务器配置，勾选后导入为本 profile 的服务器行。',
@@ -201,9 +207,15 @@ export const en = {
   confirmRemoveRoot: 'Remove this repository?',
   removeRootWarn: 'Stops scanning the repository and deletes the copy downloaded into DSH_HOME (a local folder itself is untouched).',
   mcpTitle: 'MCP servers',
-  mcpIntro: 'Manage the MCP server rows (@deepseek-ai/dsh-mcp-client) in this profile. Additions, edits, and removals take effect after a dsh restart.',
+  mcpIntro: 'Manage MCP server rows (@deepseek-ai/dsh-mcp-client). A server lives either in this profile or in the global layer (DSH_HOME/cordis.patch.yml, applied to every profile on this machine); additions, edits, and removals take effect after a dsh restart.',
   addServer: 'Add server',
   editServer: 'Edit server',
+  scopeLabel: 'Scope',
+  scopeGlobal: 'Global',
+  scopeProfile: 'This profile',
+  scopeHint: 'Global writes DSH_HOME/cordis.patch.yml and applies to every profile on this machine; this profile writes the current profile only.',
+  shadowedByGlobal: 'a global row with the same id wins — this row has no effect',
+  globalLayerError: 'Failed to read the global layer (DSH_HOME/cordis.patch.yml); global servers are hidden:',
   serverName: 'Server name (tool name prefix)',
   transport: 'Transport',
   transportStdio: 'stdio (local command)',
@@ -217,7 +229,7 @@ export const en = {
   enabled: 'Enabled',
   toggle: 'Enable/disable',
   confirmRemove: 'Remove this server?',
-  removeWarn: 'Removes the row from the profile configuration; its tools disappear after the next dsh restart.',
+  removeWarn: 'Removes the row from its configuration; its tools disappear after the next dsh restart.',
   emptyMcp: 'No MCP servers configured yet',
   importServers: 'Import from other agents',
   importIntro: 'Scans Claude Code (~/.claude.json) and Codex (~/.codex/config.toml) MCP server configs; selected entries become server rows in this profile.',

package/src/index.ts

@@ -11,7 +11,7 @@ import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { agentSkillRoots } from './agents.ts'
-import { argvProfile, profileDir } from './profile.ts'
+import { argvProfile, dshHomeDir, profileDir } from './profile.ts'
 import { mountCapabilitiesRoutes } from './routes.ts'
 import { loadState } from './state.ts'
 import type { CapabilitiesHost } from './types.ts'
@@ -102,6 +102,7 @@ export function apply(ctx: Context, config?: Config): void {
       ctx.effect(
         () => mountCapabilitiesRoutes(hostCtx as unknown as CapabilitiesHost, {
           profileDirPath: profileDir(profile),
+          dshHomePath: dshHomeDir(),
           remountProvider,
         }),
         'dsh-plugin-capabilities: http routes',

package/src/mcp.test.ts

@@ -1,11 +1,12 @@
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterAll, describe, expect, it } from 'vitest'
-import { listMcp, removeMcp, setMcpDisabled, upsertMcp, validateMcpInput, type McpInput } from './mcp.ts'
+import { listMcp, listMcpScoped, mcpScopeDir, removeMcp, setMcpDisabled, upsertMcp, validateMcpInput, type McpInput } from './mcp.ts'
 
 const root = mkdtempSync(join(tmpdir(), 'dsh-caps-mcp-'))
 const profile = join(root, 'profiles', 'web')
+const home = join(root, 'home')
 afterAll(() => rmSync(root, { recursive: true, force: true }))
 
 const patch = () => join(profile, 'cordis.patch.yml')
@@ -133,3 +134,83 @@ describe('profile patch CRUD', () => {
     expect(listMcp(profile)).toHaveLength(0)
   })
 })
+
+describe('corrupt patch file', () => {
+  it('fails reads and writes with the file path and parser location, writing nothing', () => {
+    // GitHub issue #1: a malformed cordis.patch.yml surfaced as the raw
+    // "Document with errors cannot be stringified" when a write hit String(doc).
+    const brokenDir = join(root, 'profiles', 'broken')
+    mkdirSync(brokenDir, { recursive: true })
+    writeFileSync(join(brokenDir, 'cordis.patch.yml'), 'foo: 1\n  bar: 2\n', 'utf8')
+    const before = readFileSync(join(brokenDir, 'cordis.patch.yml'), 'utf8')
+
+    expect(() => listMcp(brokenDir)).toThrow(/cordis\.patch\.yml/)
+    expect(() => listMcp(brokenDir)).toThrow(/line 1/)
+    expect(() => upsertMcp(brokenDir, stdio)).toThrow(/未写入任何内容/)
+    expect(readFileSync(join(brokenDir, 'cordis.patch.yml'), 'utf8')).toBe(before)
+  })
+})
+
+describe('global patch layer (GitHub issue #2)', () => {
+  const cleanHome = (): void => rmSync(join(home, 'cordis.patch.yml'), { force: true })
+
+  it('merges both layers, global first, and flags shadowed profile rows', () => {
+    cleanHome()
+    mkdirSync(home, { recursive: true })
+    writeFileSync(join(home, 'cordis.patch.yml'), [
+      '- insert:',
+      '    - id: mcp-shared-tools',
+      "      name: '@deepseek-ai/dsh-mcp-client'",
+      '      config:',
+      '        serverName: shared-tools',
+      '        transport: stdio',
+      '        command: node',
+      '        args:',
+      '          - global.js',
+      '',
+    ].join('\n'), 'utf8')
+
+    upsertMcp(profile, { ...stdio, serverName: 'github' })
+    // Same id as the global row: the home layer composes after the profile
+    // layer, so this profile row never takes effect.
+    upsertMcp(profile, { ...stdio, serverName: 'shared', id: 'mcp-shared-tools' })
+
+    const { servers, globalError } = listMcpScoped(profile, home)
+    expect(globalError).toBeUndefined()
+    expect(servers.map(row => `${row.scope}/${row.id}`)).toEqual(['global/mcp-shared-tools', 'profile/mcp-github', 'profile/mcp-shared-tools'])
+    expect(servers[0]).toMatchObject({ serverName: 'shared-tools', args: ['global.js'] })
+    expect(servers[2].shadowed).toBe(true)
+    expect(servers[1].shadowed).toBeUndefined()
+
+    cleanHome()
+    expect(listMcpScoped(profile, home).servers.every(row => row.scope === 'profile')).toBe(true)
+  })
+
+  it('degrades a broken global file to globalError and still lists profile rows', () => {
+    mkdirSync(home, { recursive: true })
+    writeFileSync(join(home, 'cordis.patch.yml'), 'foo: 1\n  bar: 2\n', 'utf8')
+    const { servers, globalError } = listMcpScoped(profile, home)
+    expect(globalError).toMatch(/cordis\.patch\.yml/)
+    expect(globalError).toMatch(/line 1/)
+    expect(servers.length).toBeGreaterThan(0)
+    expect(servers.every(row => row.scope === 'profile')).toBe(true)
+    cleanHome()
+  })
+
+  it('writes, toggles, and removes through the global scope dir', () => {
+    cleanHome()
+    const globalDir = mcpScopeDir('global', profile, home)
+    expect(globalDir).toBe(home)
+
+    const id = upsertMcp(globalDir, { ...stdio, serverName: 'shared-tools' })
+    expect(id).toBe('mcp-shared-tools')
+    // The global layer file (not the profile's) received the row.
+    expect(readFileSync(join(home, 'cordis.patch.yml'), 'utf8')).toContain('shared-tools')
+
+    expect(setMcpDisabled(globalDir, id, true)).toBe(true)
+    expect(listMcp(home)[0].disabled).toBe(true)
+    expect(removeMcp(globalDir, id)).toBe(true)
+    expect(listMcp(home)).toHaveLength(0)
+    expect(listMcp(profile).some(row => row.serverName === 'shared-tools')).toBe(false)
+  })
+})

package/src/mcp.ts

@@ -10,6 +10,12 @@
  * list. Managed rows therefore always sit inside one insert entry, and any
  * legacy bare rows (written before this contract was understood) are
  * absorbed into it on the next write.
+ *
+ * Rows live in one of two patch layers: the profile's own
+ * `cordis.patch.yml`, or the machine-wide `$DSH_HOME/cordis.patch.yml`
+ * (dsh composes it over every profile, after the profile layer — a home row
+ * with the same id wins). The primitives below address one layer via the
+ * directory holding its `cordis.patch.yml`; `listMcpScoped` merges both.
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
@@ -24,6 +30,9 @@ export const SERVER_NAME_RE = /^[A-Za-z0-9_-]{1,32}$/
 /** Transport choices the client supports. */
 export type McpTransport = 'stdio' | 'streamable-http'
 
+/** Which patch layer a row lives in. */
+export type McpScope = 'global' | 'profile'
+
 /** One managed row, as shown to the browser. */
 export interface McpRow {
   id: string
@@ -38,14 +47,46 @@ export interface McpRow {
   headers?: Record<string, string>
 }
 
+/** One row tagged with its layer. */
+export interface McpRowView extends McpRow {
+  scope: McpScope
+  /** Profile rows only: a global row with the same id composes after this one and wins. */
+  shadowed?: boolean
+}
+
+/** Merged listing across both patch layers. */
+export interface McpListResult {
+  servers: McpRowView[]
+  /** The home layer exists but could not be read; its rows are not shown. */
+  globalError?: string
+}
+
 /** Write request for one server row (id empty = create). */
 export type McpInput = Omit<McpRow, 'disabled'> & { disabled?: boolean }
 
-/** Load the profile patch as a YAML document; `[]` for a missing file. */
-function loadPatch(profileDirPath: string): Document {
-  const path = join(profileDirPath, 'cordis.patch.yml')
+/**
+ * Refuse to touch a patch file the parser could not fully read. parseDocument
+ * parks syntax errors in doc.errors (it does not throw), and the failure only
+ * resurfaces at String(doc) as the internals-leaking "Document with errors
+ * cannot be stringified". Nothing gets written either way, but the banner must
+ * say what is actually wrong and which file to fix.
+ */
+function assertPatchParses(path: string, doc: Document): void {
+  if (doc.errors.length === 0) return
+  const at = String(doc.errors[0].message).split('\n', 1)[0]
+  const total = doc.errors.length > 1 ? `, +${doc.errors.length - 1} more` : ''
+  throw new Error(
+    `配置文件 ${path} 存在 YAML 语法错误（${at}${total}），未写入任何内容，请修复该文件后重试`
+    + ` / YAML syntax error in the patch file (${at}${total}); nothing was written — fix it and retry`,
+  )
+}
+
+/** Load one layer's patch (`<dirPath>/cordis.patch.yml`) as a YAML document; `[]` for a missing file. */
+function loadPatch(dirPath: string): Document {
+  const path = join(dirPath, 'cordis.patch.yml')
   const text = existsSync(path) ? readFileSync(path, 'utf8') : '[]'
   const doc = parseDocument(text)
+  assertPatchParses(path, doc)
   const contents = doc.contents as YAMLSeq | null
   // The default-empty file parses as a flow `[]`; the patch layer is
   // human-edited block YAML, so flip the flag before anything appends.
@@ -53,9 +94,9 @@ function loadPatch(profileDirPath: string): Document {
   return doc
 }
 
-function savePatch(profileDirPath: string, doc: Document): void {
-  mkdirSync(profileDirPath, { recursive: true })
-  writeFileSync(join(profileDirPath, 'cordis.patch.yml'), String(doc), 'utf8')
+function savePatch(dirPath: string, doc: Document): void {
+  mkdirSync(dirPath, { recursive: true })
+  writeFileSync(join(dirPath, 'cordis.patch.yml'), String(doc), 'utf8')
 }
 
 /** Wrap a plain value into a YAML node (yaml v2 exposes no standalone createNode). */
@@ -165,12 +206,49 @@ function takenIds(doc: Document): Set<string> {
   return taken
 }
 
-/** Read every mcp-client row in the profile layer. */
-export function listMcp(profileDirPath: string): McpRow[] {
-  const doc = loadPatch(profileDirPath)
+/** Read every mcp-client row in one patch layer (`<dirPath>/cordis.patch.yml`). */
+export function listMcp(dirPath: string): McpRow[] {
+  const doc = loadPatch(dirPath)
   return mcpRowItems(doc).map(({ node }) => rowToMcp(doc, node))
 }
 
+/**
+ * Merge both patch layers for the browser: global rows first (dsh composes
+ * them after the profile layer, so they win), profile rows tagged `shadowed`
+ * when a global row claims the same id. A broken home layer must not take
+ * the whole page down — its read failure degrades to `globalError` and the
+ * profile layer still lists (the assertPatchParses message names the file
+ * and the parser location, which is what the banner shows).
+ */
+export function listMcpScoped(profileDirPath: string, dshHomePath: string): McpListResult {
+  let globalRows: McpRow[] = []
+  let globalError: string | undefined
+  if (existsSync(join(dshHomePath, 'cordis.patch.yml'))) {
+    try {
+      globalRows = listMcp(dshHomePath)
+    } catch (error) {
+      globalError = error instanceof Error ? error.message : String(error)
+    }
+  }
+  const globalIds = new Set(globalRows.map(row => row.id).filter(id => id !== ''))
+  return {
+    servers: [
+      ...globalRows.map((row): McpRowView => ({ ...row, scope: 'global' })),
+      ...listMcp(profileDirPath).map((row): McpRowView => ({
+        ...row,
+        scope: 'profile',
+        ...(globalIds.has(row.id) ? { shadowed: true } : {}),
+      })),
+    ],
+    ...(globalError !== undefined ? { globalError } : {}),
+  }
+}
+
+/** Resolve a write target: the layer's directory holding its cordis.patch.yml. */
+export function mcpScopeDir(scope: McpScope, profileDirPath: string, dshHomePath: string): string {
+  return scope === 'global' ? dshHomePath : profileDirPath
+}
+
 /** Validate one write request; returns the rejection reason or null. */
 export function validateMcpInput(input: McpInput): string | null {
   if (!SERVER_NAME_RE.test(input.serverName)) return 'serverName must be 1-32 chars of A-Z a-z 0-9 _ -'
@@ -186,9 +264,9 @@ export function validateMcpInput(input: McpInput): string | null {
 }
 
 /** Add or replace one server row. Returns the (possibly deduplicated) id. */
-export function upsertMcp(profileDirPath: string, input: McpInput): string {
+export function upsertMcp(dirPath: string, input: McpInput): string {
   const inputId = input.id ?? ''
-  const doc = loadPatch(profileDirPath)
+  const doc = loadPatch(dirPath)
   const list = managedInsert(doc)
 
   const existing = inputId !== ''
@@ -230,25 +308,25 @@ export function upsertMcp(profileDirPath: string, input: McpInput): string {
     rowSeq(doc).items.splice(rowSeq(doc).items.indexOf(existing.node), 1, node)
   }
 
-  savePatch(profileDirPath, doc)
+  savePatch(dirPath, doc)
   return id
 }
 
 /** Flip one row's disabled flag (absent = enabled). Returns false when missing. */
-export function setMcpDisabled(profileDirPath: string, id: string, disabled: boolean): boolean {
-  const doc = loadPatch(profileDirPath)
+export function setMcpDisabled(dirPath: string, id: string, disabled: boolean): boolean {
+  const doc = loadPatch(dirPath)
   managedInsert(doc)
   const hit = mcpRowItems(doc).find(({ node }) => String(node.get('id') ?? '') === id)
   if (hit === undefined) return false
   if (disabled) hit.node.set('disabled', true)
   else hit.node.delete('disabled')
-  savePatch(profileDirPath, doc)
+  savePatch(dirPath, doc)
   return true
 }
 
 /** Remove one server row. Returns false when missing. */
-export function removeMcp(profileDirPath: string, id: string): boolean {
-  const doc = loadPatch(profileDirPath)
+export function removeMcp(dirPath: string, id: string): boolean {
+  const doc = loadPatch(dirPath)
   managedInsert(doc)
   const hit = mcpRowItems(doc).find(({ node }) => String(node.get('id') ?? '') === id)
   if (hit === undefined || hit.list === undefined) return false
@@ -262,6 +340,6 @@ export function removeMcp(profileDirPath: string, id: string): boolean {
     seq.items.splice(seq.items.indexOf(owner), 1)
   }
 
-  savePatch(profileDirPath, doc)
+  savePatch(dirPath, doc)
   return true
 }

package/src/profile.ts

@@ -10,8 +10,12 @@ export function argvProfile(argv: readonly string[] = process.argv): string | un
   return undefined
 }
 
+/** The dsh home directory itself: `$DSH_HOME`, default `~/.dsh`. */
+export function dshHomeDir(dshHome: string | undefined = process.env.DSH_HOME): string {
+  return dshHome ?? join(homedir(), '.dsh')
+}
+
 /** Directory of a profile under DSH_HOME (default `~/.dsh`). */
 export function profileDir(profile: string, dshHome: string | undefined = process.env.DSH_HOME): string {
-  const home = dshHome ?? join(homedir(), '.dsh')
-  return join(home, 'profiles', profile)
+  return join(dshHomeDir(dshHome), 'profiles', profile)
 }