feat(agent-presets): give a preset a name and a description

A picker showed directory names, so the settings page could only ever list `standard` / `core-web` / `cordis` and hope the reader knew what they meant. A preset may now publish display text in an optional `preset.yml` beside its composition, and the section renders cards — name, description, and the one in use — instead of rows. The file carries display text ONLY. `id` is the directory name and `trust` comes from the root a preset was discovered under, so neither is writable there: otherwise a locally authored preset could name itself into the shipped set. It is a separate file because a composition is a top-level list of plugin rows — YAML cannot carry sibling keys beside it, and a fake metadata row would hand the Loader something to load. Every read failure degrades to no metadata; absent, malformed, wrongly typed, and blank all mean the same thing and the picker falls back to the id. Presentation is not capability: a preset whose name is broken still mounts. The editor gained name and description fields above the YAML, and clearing both removes the file rather than storing a blank name.
2026-08-05 16:30:14 +08:00
parent 5b93f48f78
commit 7281615d44
27 changed files with 593 additions and 68 deletions
--- a/packages/client/ui-agent-preset/src/client/AgentPresetSection.module.css
+++ b/packages/client/ui-agent-preset/src/client/AgentPresetSection.module.css
@@ -29,35 +29,77 @@
  color: var(--dsw-alias-label-tertiary);
 }

-.rows {
+/* Cards, not rows: a preset is a thing you pick, and the description is the
+   part that tells them apart — a row would bury it beside the actions. */
+.cards {
  list-style: none;
  margin: 0;
  padding: 0;
-  display: flex;
-  flex-direction: column;
-  gap: 10px;
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(232px, 1fr));
+  gap: 12px;
 }

-.rowCard {
+.card {
  border: 1px solid var(--dsw-alias-border-l2);
  border-radius: 12px;
-  padding: 12px 14px;
+  padding: 14px 16px;
  display: flex;
  flex-direction: column;
-  gap: 12px;
+  gap: 8px;
  background: var(--dsw-alias-bg-layer-3);
 }

-.rowHead {
+/* The default preset is the one in use; it reads as selected rather than
+   merely badged. */
+.cardActive {
+  background: var(--dsw-alias-bg-layer-2);
+  border-color: var(--dsw-alias-label-tertiary);
+}
+
+.cardHead {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+}
+
+.cardName {
+  font-size: 15px;
+  font-weight: 600;
+  line-height: 1.4;
+}
+
+.inUse {
+  margin-left: auto;
+  font-size: 11px;
+  color: var(--dsw-alias-label-tertiary);
+  white-space: nowrap;
+}
+
+.cardDesc {
+  margin: 0;
+  font-size: 13px;
+  line-height: 1.55;
+  color: var(--dsw-alias-label-secondary);
+  flex: 1;
+}
+
+.cardMeta {
  display: flex;
  align-items: center;
  gap: 8px;
-  flex-wrap: wrap;
 }

-.rowName {
-  font-size: 15px;
-  font-weight: 600;
+.cardId {
+  font-family: var(--dsw-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  font-size: 11px;
+  color: var(--dsw-alias-label-dimmed);
+}
+
+.cardFoot {
+  display: flex;
+  padding-top: 4px;
+  border-top: 1px solid var(--dsw-alias-border-l2);
 }

 .badge,
@@ -80,30 +122,38 @@

 .rowActions {
  display: inline-flex;
-  gap: 8px;
-  margin-left: auto;
+  gap: 4px;
+  flex-wrap: wrap;
+  align-items: center;
 }

 .secondaryButton {
-  border: 1px solid var(--dsw-alias-border-l2);
-  border-radius: 999px;
-  padding: 6px 14px;
-  background: var(--dsw-alias-bg-layer-3);
-  color: inherit;
+  border: none;
+  border-radius: 7px;
+  padding: 5px 8px;
+  background: none;
+  color: var(--dsw-alias-label-secondary);
  font: inherit;
-  font-size: 13px;
+  font-size: 12.5px;
  cursor: pointer;
 }

 .dangerButton {
  border: none;
+  border-radius: 7px;
+  padding: 5px 8px;
  background: none;
  color: var(--dsw-alias-state-error-primary);
  font: inherit;
-  font-size: 13px;
+  font-size: 12.5px;
  cursor: pointer;
 }

+.secondaryButton:hover:not(:disabled),
+.dangerButton:hover:not(:disabled) {
+  background: var(--dsw-alias-bg-layer-1);
+}
+
 .secondaryButton:disabled,
 .dangerButton:disabled,
 .addButton:disabled {
--- a/packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx
+++ b/packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx
@@ -35,6 +35,10 @@ export interface AgentPresetSectionInjected {
  setId: (id: string) => void
  /** Replace the draft's composition text. */
  setContent: (content: string) => void
+  /** Rename the draft. */
+  setName: (name: string) => void
+  /** Replace the draft's description. */
+  setDescription: (description: string) => void
  /** Save the open draft. */
  save: () => Promise<void>
  /** Ask for delete confirmation, or dismiss it with null. */
@@ -56,7 +60,8 @@ interface EditorProps {
  draft: PresetDraft
  blocker: ReturnType<typeof draftBlocker>
  t: (key: AgentPresetSettingsKey) => string
-  actions: Pick<AgentPresetSectionInjected, 'close' | 'save' | 'setContent' | 'setId'>
+  actions: Pick<AgentPresetSectionInjected,
+    'close' | 'save' | 'setContent' | 'setDescription' | 'setId' | 'setName'>
 }

 function Editor({ draft, blocker, t, actions }: EditorProps): ReactNode {
@@ -66,19 +71,44 @@ function Editor({ draft, blocker, t, actions }: EditorProps): ReactNode {
      {draft.creating
        ? (
          <label className={css.field}>
-            <span className={css.fieldLabel}>{t('presetName')}</span>
+            <span className={css.fieldLabel}>{t('presetId')}</span>
            <input
              className={css.input}
              value={draft.id}
              autoFocus
              spellCheck={false}
-              placeholder={t('presetNamePlaceholder')}
+              placeholder={t('presetIdPlaceholder')}
              onChange={(event) => { actions.setId(event.target.value) }}
            />
            <span className={css.hint}>{`${t('copyOf')} ${draft.source}`}</span>
          </label>
        )
        : null}
+      {draft.writable
+        ? (
+          <>
+            <label className={css.field}>
+              <span className={css.fieldLabel}>{t('displayName')}</span>
+              <input
+                className={css.input}
+                value={draft.name}
+                spellCheck={false}
+                placeholder={draft.id === '' ? t('displayNamePlaceholder') : draft.id}
+                onChange={(event) => { actions.setName(event.target.value) }}
+              />
+            </label>
+            <label className={css.field}>
+              <span className={css.fieldLabel}>{t('displayDescription')}</span>
+              <input
+                className={css.input}
+                value={draft.description}
+                placeholder={t('displayDescriptionPlaceholder')}
+                onChange={(event) => { actions.setDescription(event.target.value) }}
+              />
+            </label>
+          </>
+        )
+        : null}
      {draft.writable ? null : <p className={css.notice}>{t('readOnlyNotice')}</p>}
      <label className={css.field}>
        <span className={css.fieldLabel}>{t('composition')}</span>
@@ -142,20 +172,33 @@ export function AgentPresetSection(props: AgentPresetSectionProps): ReactNode {

  const { draft } = state
  const blocker = draft === null ? undefined : draftBlocker(draft, state.rows)
-  const editorActions = { close: props.close, save: props.save, setContent: props.setContent, setId: props.setId }
+  const editorActions = {
+    close: props.close,
+    save: props.save,
+    setContent: props.setContent,
+    setDescription: props.setDescription,
+    setId: props.setId,
+    setName: props.setName,
+  }

  return (
    <div className={css.section}>
      <h2 className={css.title}>{t('nav')}</h2>
      <p className={css.intro}>{t('sectionIntro')}</p>
      {state.error === null ? null : <p className={css.error} role="alert">{state.error}</p>}
-      <ul className={css.rows}>
+      <ul className={css.cards}>
        {state.rows.map(row => (
-          <li key={row.id} className={css.rowCard}>
-            <div className={css.rowHead}>
-              <span className={css.rowName}>{row.id}</span>
+          <li key={row.id} className={row.isDefault ? `${css.card} ${css.cardActive}` : css.card}>
+            <div className={css.cardHead}>
+              <span className={css.cardName}>{row.name ?? row.id}</span>
+              {row.isDefault ? <span className={css.inUse}>{t('inUse')}</span> : null}
+            </div>
+            <p className={css.cardDesc}>{row.description ?? t('noDescription')}</p>
+            <div className={css.cardMeta}>
              <span className={css.badge}>{row.trust === 'user' ? t('userTrust') : t('builtIn')}</span>
-              {row.isDefault ? <span className={css.defaultBadge}>{t('defaultBadge')}</span> : null}
+              <code className={css.cardId}>{row.id}</code>
+            </div>
+            <div className={css.cardFoot}>
              <span className={css.rowActions}>
                {row.isDefault
                  ? null
--- a/packages/client/ui-agent-preset/src/client/index.ts
+++ b/packages/client/ui-agent-preset/src/client/index.ts
@@ -113,6 +113,8 @@ export function apply(ctx: ClientContext): void {
    close: () => { section.close() },
    setId: (id: string) => { section.setId(id) },
    setContent: (content: string) => { section.setContent(content) },
+    setName: (name: string) => { section.setName(name) },
+    setDescription: (description: string) => { section.setDescription(description) },
    save: () => section.save(),
    confirmDelete: (id: string | null) => { section.confirmDelete(id) },
    remove: () => section.remove(),
--- a/packages/client/ui-agent-preset/src/client/locales.ts
+++ b/packages/client/ui-agent-preset/src/client/locales.ts
@@ -4,7 +4,9 @@
 export type AgentPresetSettingsKey =
  | 'title' | 'description' | 'loading' | 'error' | 'userTrust' | 'seatHint' | 'lockedHint'
  | 'nav' | 'sectionIntro' | 'builtIn' | 'defaultBadge' | 'setDefault' | 'edit' | 'view'
-  | 'duplicate' | 'delete' | 'newPreset' | 'presetName' | 'presetNamePlaceholder' | 'copyOf'
+  | 'duplicate' | 'delete' | 'newPreset' | 'presetId' | 'presetIdPlaceholder' | 'copyOf'
+  | 'displayName' | 'displayNamePlaceholder' | 'displayDescription' | 'displayDescriptionPlaceholder'
+  | 'inUse' | 'noDescription'
  | 'composition' | 'readOnlyNotice' | 'save' | 'saving' | 'cancel' | 'close' | 'retry'
  | 'idRequired' | 'idInvalid' | 'idTaken'
  | 'deleteTitle' | 'deleteDescription' | 'deleteConfirm' | 'deleting'
@@ -30,8 +32,14 @@ export const en: Record<AgentPresetSettingsKey, string> = {
  duplicate: 'Duplicate',
  delete: 'Delete',
  newPreset: 'New preset',
-  presetName: 'Preset name',
-  presetNamePlaceholder: 'my-agent',
+  presetId: 'Identifier',
+  presetIdPlaceholder: 'my-agent',
+  displayName: 'Name',
+  displayNamePlaceholder: 'Shown in the picker',
+  displayDescription: 'Description',
+  displayDescriptionPlaceholder: 'One sentence on what this preset is for',
+  inUse: 'In use',
+  noDescription: 'No description.',
  copyOf: 'Copied from',
  composition: 'Composition (cordis.yml)',
  readOnlyNotice: 'This preset ships with the deployment and cannot be edited. Duplicate it to make your own.',
@@ -40,9 +48,9 @@ export const en: Record<AgentPresetSettingsKey, string> = {
  cancel: 'Cancel',
  close: 'Close',
  retry: 'Retry',
-  idRequired: 'Name the preset.',
+  idRequired: 'Give the preset an identifier.',
  idInvalid: 'Use lowercase letters, digits, and hyphens, starting with a letter or digit.',
-  idTaken: 'A preset with this name already exists.',
+  idTaken: 'A preset with this identifier already exists.',
  deleteTitle: 'Delete this preset?',
  deleteDescription:
    'The composition file is deleted. Sessions already running on it keep working; new sessions cannot select it.',
@@ -69,8 +77,14 @@ export const zh: Record<AgentPresetSettingsKey, string> = {
  duplicate: '复制',
  delete: '删除',
  newPreset: '新建预设',
-  presetName: '预设名称',
-  presetNamePlaceholder: 'my-agent',
+  presetId: '标识符',
+  presetIdPlaceholder: 'my-agent',
+  displayName: '名称',
+  displayNamePlaceholder: '选择器中显示的名字',
+  displayDescription: '描述',
+  displayDescriptionPlaceholder: '一句话说明这个预设做什么',
+  inUse: '当前使用',
+  noDescription: '暂无描述。',
  copyOf: '复制自',
  composition: '组装（cordis.yml）',
  readOnlyNotice: '该预设随部署提供，不可编辑。复制一份即可改成自己的。',
@@ -81,7 +95,7 @@ export const zh: Record<AgentPresetSettingsKey, string> = {
  retry: '重试',
  idRequired: '请填写预设名称。',
  idInvalid: '只能使用小写字母、数字与连字符，且以字母或数字开头。',
-  idTaken: '同名预设已存在。',
+  idTaken: '该标识符已被占用。',
  deleteTitle: '删除该预设？',
  deleteDescription: '组装文件将被删除。已在其上运行的会话不受影响；新会话将无法再选择它。',
  deleteConfirm: '删除',
--- a/packages/client/ui-agent-preset/src/client/section-store.ts
+++ b/packages/client/ui-agent-preset/src/client/section-store.ts
@@ -17,8 +17,12 @@ const PRESET_ID = /^[a-z0-9][a-z0-9-]*$/

 /** One preset row the page renders. */
 export interface PresetRow {
-  /** Preset id, also its display name and directory name. */
+  /** Preset id and directory name; the display name falls back to it. */
  id: string
+  /** Display name the preset published, absent when it published none. */
+  name?: string
+  /** One sentence on what the preset is for. */
+  description?: string
  /** Whether the preset ships with the deployment or was authored locally. */
  trust: 'system' | 'user'
  /** Whether a session that names no preset gets this one. */
@@ -42,6 +46,10 @@ export interface PresetDraft {
  writable: boolean
  /** Whether a save is in flight. */
  saving: boolean
+  /** Display name being edited; empty means the picker falls back to the id. */
+  name: string
+  /** Description being edited. */
+  description: string
  /** The last save failure, cleared by the next edit. */
  error: string | null
 }
@@ -172,7 +180,7 @@ export class AgentPresetSectionController {
        this.set({ error: response.result.error.message })
        return
      }
-      const { content, writable } = response.result.value
+      const { content, writable, name, description } = response.result.value
      this.set({
        draft: {
          id: creating ? '' : source,
@@ -182,6 +190,10 @@ export class AgentPresetSectionController {
          // A copy is always writable: it lands in the local root regardless of
          // where the text came from.
          writable: creating || writable,
+          // A copy starts from the source's text but must be renamed, or two
+          // rows would present themselves identically.
+          name: creating ? '' : name ?? '',
+          description: description ?? '',
          saving: false,
          error: null,
        },
@@ -212,6 +224,22 @@ export class AgentPresetSectionController {
    this.patchDraft({ content, error: null })
  }

+  /**
+   * Rename the draft.
+   * @param name - the display name typed into the editor.
+   */
+  setName(name: string): void {
+    this.patchDraft({ name, error: null })
+  }
+
+  /**
+   * Replace the draft's description.
+   * @param description - the description typed into the editor.
+   */
+  setDescription(description: string): void {
+    this.patchDraft({ description, error: null })
+  }
+
  /**
   * Save the open draft, then re-read the roster.
   *
@@ -225,7 +253,12 @@ export class AgentPresetSectionController {
    if (draftBlocker(draft, this.store.getSnapshot().rows) !== undefined) return
    this.patchDraft({ saving: true, error: null })
    try {
-      const response = await this.api.agentPresets.write({ agentPreset: draft.id, content: draft.content })
+      const response = await this.api.agentPresets.write({
+        agentPreset: draft.id,
+        content: draft.content,
+        name: draft.name,
+        description: draft.description,
+      })
      if (!response.result.ok) {
        this.patchDraft({ saving: false, error: response.result.error.message })
        return
--- a/packages/client/ui-agent-preset/tests/apply.spec.ts
+++ b/packages/client/ui-agent-preset/tests/apply.spec.ts
@@ -131,6 +131,8 @@ describe('ui-agent-preset apply', () => {
    await section.load()
    section.setId('mine')
    section.setContent('- id: x\n')
+    section.setName('我的模式')
+    section.setDescription('只做检索。')
    section.confirmDelete('mine')
    section.close()
    await Promise.all([section.open('standard'), section.createFrom(), section.save(), section.remove()])
--- a/packages/client/ui-agent-preset/tests/section-store.spec.ts
+++ b/packages/client/ui-agent-preset/tests/section-store.spec.ts
@@ -272,7 +272,8 @@ describe('creating a preset', () => {

 describe('the save blocker', () => {
  const base: PresetDraft = {
-    id: '', source: 'standard', creating: true, content: '', writable: true, saving: false, error: null,
+    id: '', source: 'standard', creating: true, content: '', writable: true,
+    name: '', description: '', saving: false, error: null,
  }
  const rows: readonly PresetRow[] = [{ id: 'mine', trust: 'user', isDefault: false }]

@@ -405,11 +406,37 @@ describe('saving', () => {
    expect(draftOf(controller).error).toBeNull()
  })

+  it('carries the display name and description through a save', async () => {
+    const { controller, calls } = harness()
+    await controller.load()
+    await controller.open('mine')
+
+    controller.setName('我的模式')
+    controller.setDescription('只做检索。')
+    await controller.save()
+
+    expect(calls.find(call => call.method === 'write')?.payload)
+      .toMatchObject({ agentPreset: 'mine', name: '我的模式', description: '只做检索。' })
+  })
+
+  it('leaves a copy unnamed so two rows cannot present themselves alike', async () => {
+    const { controller } = harness()
+    await controller.load()
+
+    await controller.createFrom('mine')
+
+    // The composition is copied verbatim; the display name is not.
+    expect(draftOf(controller)).toMatchObject({ id: '', name: '' })
+    expect(draftOf(controller).content).toBe('- id: tool-read\n')
+  })
+
  it('ignores an edit with no draft open', () => {
    const { controller } = harness()

    controller.setId('x')
    controller.setContent('y')
+    controller.setName('n')
+    controller.setDescription('d')

    expect(controller.store.getSnapshot().draft).toBeNull()
  })
--- a/packages/client/ui-agent-preset/tests/section.spec.tsx
+++ b/packages/client/ui-agent-preset/tests/section.spec.tsx
@@ -22,7 +22,7 @@ const READY: AgentPresetSectionState = {
  error: null,
  authorable: true,
  rows: [
-    { id: 'standard', trust: 'system', isDefault: true },
+    { id: 'standard', trust: 'system', isDefault: true, name: '标准模式', description: '完整的编码 agent。' },
    { id: 'mine', trust: 'user', isDefault: false },
  ],
  draft: null,
@@ -44,6 +44,8 @@ function renderSection(state: Partial<AgentPresetSectionState> = {}) {
    close: vi.fn(),
    setId: vi.fn(),
    setContent: vi.fn(),
+    setName: vi.fn(),
+    setDescription: vi.fn(),
    save: vi.fn(() => Promise.resolve()),
    confirmDelete: vi.fn(),
    remove: vi.fn(() => Promise.resolve()),
@@ -58,10 +60,12 @@ function renderSection(state: Partial<AgentPresetSectionState> = {}) {
  return actions
 }

+/** Locate a card by the id it prints, not by its display name. */
 function rowFor(id: string): HTMLElement {
-  const row = screen.getByText(id).closest('li')
-  /* v8 ignore next -- every rendered row id resolves to its card */
-  if (row === null) throw new Error(`no row for ${id}`)
+  const key = screen.getAllByText(id).find(node => node.tagName === 'CODE')
+  const row = key?.closest('li') ?? null
+  /* v8 ignore next -- every rendered card prints its id */
+  if (row === null) throw new Error(`no card for ${id}`)
  return row
 }

@@ -72,12 +76,24 @@ describe('the preset list', () => {
    await waitFor(() => { expect(actions.load).toHaveBeenCalledTimes(1) })
  })

-  it('marks trust and the default, and offers no "set default" on the default row', () => {
+  it('shows the published name and description, falling back to the id', () => {
+    renderSection()
+
+    // The name is what a picker reads; the id stays visible as the key the
+    // composition and the session header actually carry.
+    expect(screen.getByText('标准模式')).toBeTruthy()
+    expect(screen.getByText('完整的编码 agent。')).toBeTruthy()
+    const mine = rowFor('mine')
+    expect(within(mine).getAllByText('mine').length).toBeGreaterThan(0)
+    expect(within(mine).getByText(en.noDescription)).toBeTruthy()
+  })
+
+  it('marks trust and the one in use, and offers no "set default" on it', () => {
    renderSection()

    const standard = rowFor('standard')
    expect(within(standard).getByText(en.builtIn)).toBeTruthy()
-    expect(within(standard).getByText(en.defaultBadge)).toBeTruthy()
+    expect(within(standard).getByText(en.inUse)).toBeTruthy()
    expect(within(standard).queryByText(en.setDefault)).toBeNull()
    expect(within(rowFor('mine')).getByText(en.userTrust)).toBeTruthy()
  })
@@ -151,13 +167,13 @@ describe('the preset list', () => {
 describe('the composition editor', () => {
  const draft = {
    id: 'mine', source: 'mine', creating: false, content: '- id: tool-read\n',
-    writable: true, saving: false, error: null,
+    writable: true, name: '我的预设', description: '', saving: false, error: null,
  }

  it('opens under the row it belongs to and edits through the controller', () => {
    const actions = renderSection({ draft })

-    const editor = within(rowFor('mine')).getByRole('textbox')
+    const editor = within(rowFor('mine')).getByLabelText(en.composition)
    expect(editor).toHaveProperty('value', '- id: tool-read\n')
    fireEvent.change(editor, { target: { value: '- id: tool-edit\n' } })

@@ -185,7 +201,7 @@ describe('the composition editor', () => {
  it('shows a shipped composition read-only, with no way to save it', () => {
    renderSection({ draft: { ...draft, id: 'standard', source: 'standard', writable: false } })

-    expect(screen.getByRole('textbox')).toHaveProperty('readOnly', true)
+    expect(screen.getByLabelText(en.composition)).toHaveProperty('readOnly', true)
    expect(screen.getByText(en.readOnlyNotice)).toBeTruthy()
    expect(screen.queryByText(en.save)).toBeNull()
    expect(screen.getByText(en.close)).toBeTruthy()
@@ -197,11 +213,28 @@ describe('the composition editor', () => {
    })

    expect(screen.getByText(`${en.copyOf} standard`)).toBeTruthy()
-    fireEvent.change(screen.getByPlaceholderText(en.presetNamePlaceholder), { target: { value: 'my-agent' } })
+    fireEvent.change(screen.getByPlaceholderText(en.presetIdPlaceholder), { target: { value: 'my-agent' } })

    expect(actions.setId).toHaveBeenCalledWith('my-agent')
  })

+  it('edits the display name and description through the controller', () => {
+    const actions = renderSection({ draft })
+
+    fireEvent.change(screen.getByLabelText(en.displayName), { target: { value: '我的模式' } })
+    fireEvent.change(screen.getByLabelText(en.displayDescription), { target: { value: '只做检索。' } })
+
+    expect(actions.setName).toHaveBeenCalledWith('我的模式')
+    expect(actions.setDescription).toHaveBeenCalledWith('只做检索。')
+  })
+
+  it('offers no display fields on a read-only preset', () => {
+    renderSection({ draft: { ...draft, writable: false } })
+
+    // Nothing here can be saved, so an editable name would be a lie.
+    expect(screen.queryByLabelText(en.displayName)).toBeNull()
+  })
+
  it('blocks a save the host would refuse, and says why', () => {
    const actions = renderSection({
      draft: { ...draft, id: 'Upper Case', source: 'standard', creating: true },