@yeaft/webchat-agent 1.0.177 → 1.0.178

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.177",
+  "version": "1.0.178",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

package/yeaft/vp/registry.js

@@ -27,8 +27,8 @@ export class Registry {
   /**
    * Replace a VP's persona fields in-place, preserving identity so any
    * downstream reference keeps its handle stable across hot-reload.
-   * Fields copied: name, role, traits, modelHint, persona, personaHash,
-   * mtimeMs.
+   * Fields copied: localized identity metadata, aliases, role, traits,
+   * modelHint, persona, personaHash, planInstruction, and mtimeMs.
    */
   updateVpInPlace(next) {
     const cur = this.vpMap.get(next.id);
@@ -37,11 +37,18 @@ export class Registry {
       return next;
     }
     cur.name = next.name;
+    cur.nameZh = next.nameZh;
+    cur.aliases = next.aliases;
+    cur.description = next.description;
+    cur.descriptionZh = next.descriptionZh;
     cur.role = next.role;
+    cur.roleZh = next.roleZh;
+    cur.area = next.area;
     cur.traits = next.traits;
     cur.modelHint = next.modelHint;
     cur.persona = next.persona;
     cur.personaHash = next.personaHash;
+    cur.planInstruction = next.planInstruction;
     cur.mtimeMs = next.mtimeMs;
     // dir / memoryDir / id stable
     return cur;

package/yeaft/vp/seed-defaults.js

@@ -1,14 +1,14 @@
 /**
- * seed-defaults.js — task-337: first-run seed of 33 default Virtual Persons.
+ * seed-defaults.js — task-337: first-run seed of 34 default Virtual Persons.
  *
  * Problem: A brand-new VP library is empty, and asking the user to author
  * dozens of personas before they can even start chatting is a non-starter.
  *
- * Solution: On first-run (libDir empty or missing), materialise 33 classic
+ * Solution: On first-run (libDir empty or missing), materialise 34 classic
  * personas with hand-crafted prompts so the session experience works
- * out of the box. Originally 12 (engineering/design/science/security/business);
- * expanded to 32 by adding philosophy / psychology / strategy / history /
- * investing / business / writing / science / arts (task: VP roster expansion).
+ * out of the box. The original engineering/design/science/security/business
+ * roster was expanded with philosophy, psychology, strategy, history,
+ * investing, writing, arts, a generalist, and a cloud-scale language architect.
  *
  * Idempotent: if ANY VP directory already exists under libDir, this is a
  * no-op. We never overwrite user-authored VPs, never "upgrade" existing
@@ -34,14 +34,14 @@ import { DEFAULT_VP_LIB_DIR } from './vp-store.js';
 import { STOCK_VP_IDS } from './stock-ids.js';
 
 /**
- * The 33 default VPs. Each entry is a valid `createVp` payload.
+ * The 34 default VPs. Each entry is a valid `createVp` payload.
  * Persona bodies are authored directly per stock member in English and Chinese.
  * Legacy bodies are kept only for exact-match safe upgrades.
  *
- * Order is intentional: the original 12 (engineering/design/science/security/
- * business) come first, then the 20 expansion VPs organized by area, followed by
- * the generalist entry point. Sidebar organization by area is a future PR; today
- * the field is data-only.
+ * Order is intentional: the core engineering/design/science/security/business
+ * roster comes first, then the expansion VPs organized by area, followed by the
+ * generalist entry point. Sidebar organization by area is a future PR; today the
+ * field is data-only.
  */
 const DEFAULT_VP_DEFINITIONS = Object.freeze([
   {
@@ -167,6 +167,35 @@ Good for: PR reviews, legacy cleanup, architecture conversations, naming debates
 Bad for: greenfield scaffolding from zero, raw performance tuning, UI design.`,
   },
 
+  {
+    vpId: 'anders',
+    displayName: 'Anders Hejlsberg',
+    displayNameZh: '安德斯·海尔斯伯格',
+    aliases: ['anders', 'hejlsberg', 'andesi', 'haierxiboge'],
+    role: 'Language and Cloud Systems Architect',
+    roleZh: '语言与云系统架构师',
+    description: 'Language design, API compatibility, and reliable cloud-scale evolution',
+    descriptionZh: '语言设计、API 兼容性与可靠的云规模演进',
+    area: 'engineering',
+    traits: [
+      'language-design', 'reliability', 'backward-compatibility',
+      'observability', 'operational-simplicity', 'incremental-evolution',
+      'ownership-boundaries',
+    ],
+    modelHint: 'primary',
+    personaEn: `You are Anders Hejlsberg. You designed C#, TypeScript, and Turbo Pascal. You review code as if it belongs to a large-scale Azure service with millions of users, where a locally elegant choice can become an operational liability at fleet scale.
+
+You prioritize reliability, backward compatibility, observability, operational simplicity, safe incremental evolution, and clear ownership boundaries. Language and API design matter because contracts outlive implementations; migrations, failure modes, diagnostics, and rollback paths are part of the design, not afterthoughts.
+
+Users bring you language, API, platform, and cloud-service changes. Show them the contract that can evolve safely, the compatibility hazards, the operational signals, and the smallest rollout that proves the change. Reject solutions that are beautiful in isolation but difficult to operate across a large service.`,
+    personaZh: `你是安德斯·海尔斯伯格。你设计了 C#、TypeScript 和 Turbo Pascal。你把代码当作服务于数百万用户的 Azure 级系统来评审：局部看似优雅的选择，到了大规模运行环境里可能就是长期运维负担。
+
+你优先考虑可靠性、向后兼容、可观测性、运维简洁、安全的增量演进和清晰的责任边界。语言与 API 设计的核心是长期契约；迁移路径、失败模式、诊断能力和回滚方案本来就是设计的一部分。
+
+用户通常带来语言、API、平台或云服务改动。你会指出能够安全演进的契约、兼容性风险、必要的运行信号，以及验证改动的最小发布步骤。你拒绝那些孤立看很漂亮、在云规模下却难以运营的方案。`,
+    legacyPersonaEn: '',
+  },
+
   {
     vpId: 'dieter',
     displayName: 'Dieter Rams',
@@ -1401,6 +1430,42 @@ Answer style: concise, organized, and forward-moving. When routing is needed, ro
   }
 ]);
 
+const DEFAULT_VP_DESCRIPTIONS = Object.freeze({
+  steve: ['Product vision, ruthless prioritization, and launch narrative', '产品愿景、果断取舍与发布叙事'],
+  linus: ['Implementation, root-cause debugging, performance, and reliability', '代码实现、根因排查、性能与可靠性'],
+  martin: ['Code review, refactoring, architecture boundaries, and maintainability', '代码评审、重构、架构边界与可维护性'],
+  dieter: ['Minimal UI, design systems, and usability review', '极简界面、设计系统与可用性评审'],
+  ada: ['Algorithms, data structures, and formal modeling', '算法、数据结构与形式化建模'],
+  grace: ['Debugging, runtime behavior, and clear technical explanation', '调试、运行时行为与清晰技术解释'],
+  alice: ['Threat modeling, authorization boundaries, and input security', '威胁建模、授权边界与输入安全'],
+  ken: ['Unix systems, simple interfaces, and composable architecture', 'Unix 系统、简单接口与可组合架构'],
+  margaret: ['Mission-critical testing, failure handling, and release quality', '关键任务测试、故障处理与发布质量'],
+  shannon: ['Information theory, metrics, and signal extraction', '信息论、指标设计与信号提取'],
+  alan: ['Object models, system architecture, and future-facing design', '对象模型、系统架构与前瞻设计'],
+  norman: ['User research, cognitive load, and interaction design', '用户研究、认知负担与交互设计'],
+  kongzi: ['Ethics, social order, and long-term conduct', '伦理、社会秩序与长期行为准则'],
+  socrates: ['Assumption testing, precise questions, and logical clarity', '假设检验、精准追问与逻辑澄清'],
+  nietzsche: ['Values critique, hidden motives, and bold reframing', '价值批判、隐性动机与大胆重构问题'],
+  kahneman: ['Cognitive bias, decision quality, and experiment design', '认知偏差、决策质量与实验设计'],
+  jung: ['Archetypes, motivation, and narrative psychology', '原型、动机与叙事心理学'],
+  sunzi: ['Strategy, positioning, leverage, and conflict avoidance', '战略、定位、杠杆与避战'],
+  clausewitz: ['Strategic friction, uncertainty, and execution under pressure', '战略摩擦、不确定性与压力下执行'],
+  simaqian: ['Historical context, causality, and durable narratives', '历史语境、因果关系与长期叙事'],
+  harari: ['Macro trends, institutions, and long-horizon consequences', '宏观趋势、制度与长期影响'],
+  buffett: ['Business quality, valuation, and durable advantages', '企业质量、估值与持久竞争优势'],
+  munger: ['Mental models, incentives, and decision debiasing', '多元思维模型、激励与决策纠偏'],
+  dalio: ['Principles, feedback loops, and organizational systems', '原则、反馈回路与组织系统'],
+  bezos: ['Customer obsession, long-term bets, and operational mechanisms', '客户执念、长期投入与运营机制'],
+  drucker: ['Management, organizational focus, and measurable outcomes', '管理、组织聚焦与可衡量成果'],
+  luxun: ['Sharp criticism, cultural diagnosis, and concise writing', '尖锐批评、文化诊断与精炼写作'],
+  sudongpo: ['Elegant writing, broad perspective, and humane judgment', '优雅写作、开阔视角与人文判断'],
+  borges: ['Conceptual structures, nonlinear narrative, and intellectual play', '概念结构、非线性叙事与智性想象'],
+  einstein: ['First principles, thought experiments, and radical simplification', '第一性原理、思想实验与极致简化'],
+  kubrick: ['Visual storytelling, pacing, and exacting creative control', '视觉叙事、节奏与严格创作控制'],
+  miyazaki: ['World-building, emotional storytelling, and humane imagination', '世界构建、情感叙事与人文想象'],
+  omni: ['Requirement clarification, workflow routing, and delivery coordination', '需求澄清、流程路由与交付协调'],
+});
+
 const LEGACY_DEFAULT_VP_PERSONA_ZH = Object.freeze({
   steve: {
     roleZh: '产品战略家',
@@ -1873,10 +1938,13 @@ function localizeDefaultVpPersona(vp) {
   const personaZh = String(vp.personaZh || '').trim();
   const legacyPersonaEn = String(vp.legacyPersonaEn || '').trim();
   const legacyPersonaZh = String(legacyZh?.persona || '').trim();
+  const descriptions = DEFAULT_VP_DESCRIPTIONS[vp.vpId] || [];
 
   return {
     ...vp,
     roleZh: vp.roleZh || legacyZh?.roleZh || '',
+    description: String(vp.description || descriptions[0] || vp.role || '').trim(),
+    descriptionZh: String(vp.descriptionZh || descriptions[1] || vp.roleZh || legacyZh?.roleZh || descriptions[0] || vp.role || '').trim(),
     persona: localizedPersonaSections(personaEn, personaZh),
     personaEn,
     personaZh,
@@ -1946,7 +2014,7 @@ function libraryHasAnyVp(libDir) {
 }
 
 /**
- * Seed the 33 default VPs into `libDir` if and only if the library is empty.
+ * Seed the 34 default VPs into `libDir` if and only if the library is empty.
  *
  * Idempotent: returns `{ seeded: 0, skipped: true }` on every call after the
  * first one (or when the user has any VP at all, including manually-created).

package/yeaft/vp/seed-topup.js

@@ -3,8 +3,9 @@
  *
  * Problem: `seedDefaultVps` is first-run-only — once the library has any VP
  * in it, that function never runs again. When we expanded the default roster
- * from 12 to 33 (philosophy, psychology, strategy, history, investing,
- * business, writing, science, arts, Omni), existing installs would never see the
+ * beyond the original 12 (philosophy, psychology, strategy, history,
+ * investing, business, writing, science, arts, Omni, and later additions),
+ * existing installs would never see the
  * new VPs without either (a) the user manually deleting their library or
  * (b) a forced overwrite that would clobber their hand edits.
  *
@@ -15,7 +16,8 @@
  *      on disk, `createVp()` it. This keeps product-owned defaults such as
  *      Omni and the expanded role roster visible in session/member pickers.
  *
- *   2. **Backfill missing stock frontmatter** (`area`, `nameZh`, `roleZh`) on
+ *   2. **Backfill missing stock frontmatter** (`area`, `nameZh`, `description`,
+ *      `descriptionZh`, `roleZh`) on
  *      existing seeded VPs whose role.md predates those fields. The persona body
  *      is left BYTE-IDENTICAL for these metadata backfills. If the user has
  *      authored their own value, we keep theirs.
@@ -176,10 +178,11 @@ function insertFrontmatterLine(source, key, value) {
   const lines = yaml.split(/\r?\n/);
   const roleIdx = lines.findIndex(l => /^role:\s*/.test(l));
   // Quote the value when it contains characters YAML treats specially or
-  // non-ASCII bytes — the existing vp-crud writer does the same dance.
+  // non-ASCII bytes. Single quotes keep backslashes and double quotes literal;
+  // doubled apostrophes are reversed by vp-store's scalar parser.
   const needsQuote = /[:#"'\\\n]/.test(valTrim) || /[^\x20-\x7e]/.test(valTrim);
   const yamlVal = needsQuote
-    ? `"${valTrim.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
+    ? `'${valTrim.replace(/'/g, "''")}'`
     : valTrim;
   const newLine = `${key}: ${yamlVal}`;
   if (roleIdx >= 0) {
@@ -216,6 +219,16 @@ export function insertNameZhLine(source, nameZh) {
   return insertFrontmatterLine(source, 'nameZh', nameZh);
 }
 
+/** Backfill `description:` into role.md frontmatter. */
+export function insertDescriptionLine(source, description) {
+  return insertFrontmatterLine(source, 'description', description);
+}
+
+/** Backfill `descriptionZh:` into role.md frontmatter. */
+export function insertDescriptionZhLine(source, descriptionZh) {
+  return insertFrontmatterLine(source, 'descriptionZh', descriptionZh);
+}
+
 /**
  * Backfill `roleZh:` into role.md frontmatter.
  *
@@ -272,6 +285,8 @@ function isObsoleteOmniAssistantBody(vp, body) {
  *   added: string[],
  *   areaBackfilled: string[],
  *   nameZhBackfilled: string[],
+ *   descriptionBackfilled: string[],
+ *   descriptionZhBackfilled: string[],
  *   roleZhBackfilled: string[],
  *   personaBackfilled: string[],
  *   respectedDeletes: string[],
@@ -283,6 +298,8 @@ export function topUpDefaultVps(libDir = DEFAULT_VP_LIB_DIR) {
   const added = [];
   const areaBackfilled = [];
   const nameZhBackfilled = [];
+  const descriptionBackfilled = [];
+  const descriptionZhBackfilled = [];
   const roleZhBackfilled = [];
   const personaBackfilled = [];
   const respectedDeletes = [];
@@ -294,7 +311,7 @@ export function topUpDefaultVps(libDir = DEFAULT_VP_LIB_DIR) {
   // that case there's nothing to top up — seedDefaultVps will populate
   // everything. We still return cleanly.
   if (!existsSync(libDir)) {
-    return { added, areaBackfilled, nameZhBackfilled, roleZhBackfilled, personaBackfilled, respectedDeletes, skippedExisting, errors };
+    return { added, areaBackfilled, nameZhBackfilled, descriptionBackfilled, descriptionZhBackfilled, roleZhBackfilled, personaBackfilled, respectedDeletes, skippedExisting, errors };
   }
 
   let versions = readSeedVersions(libDir);
@@ -373,6 +390,44 @@ export function topUpDefaultVps(libDir = DEFAULT_VP_LIB_DIR) {
           });
         }
       }
+      if (vp.description) {
+        try {
+          const src = readRole();
+          if (src != null) {
+            const patched = insertDescriptionLine(src, vp.description);
+            if (patched != null && patched !== src) {
+              writeFileSync(rolePath, patched, 'utf-8');
+              currentSrc = patched;
+              descriptionBackfilled.push(vpId);
+            }
+          }
+        } catch (err) {
+          errors.push({
+            vpId,
+            code: 'description_backfill_failed',
+            message: String(err?.message || err),
+          });
+        }
+      }
+      if (vp.descriptionZh) {
+        try {
+          const src = readRole();
+          if (src != null) {
+            const patched = insertDescriptionZhLine(src, vp.descriptionZh);
+            if (patched != null && patched !== src) {
+              writeFileSync(rolePath, patched, 'utf-8');
+              currentSrc = patched;
+              descriptionZhBackfilled.push(vpId);
+            }
+          }
+        } catch (err) {
+          errors.push({
+            vpId,
+            code: 'description_zh_backfill_failed',
+            message: String(err?.message || err),
+          });
+        }
+      }
       if (vp.roleZh) {
         try {
           const src = readRole();
@@ -452,5 +507,5 @@ export function topUpDefaultVps(libDir = DEFAULT_VP_LIB_DIR) {
   }
 
   writeSeedVersions(libDir, versions);
-  return { added, areaBackfilled, nameZhBackfilled, roleZhBackfilled, personaBackfilled, respectedDeletes, skippedExisting, errors };
+  return { added, areaBackfilled, nameZhBackfilled, descriptionBackfilled, descriptionZhBackfilled, roleZhBackfilled, personaBackfilled, respectedDeletes, skippedExisting, errors };
 }

package/yeaft/vp/stock-ids.js

@@ -25,7 +25,7 @@
 
 const STOCK_VP_ID_LIST = Object.freeze([
   // engineering
-  'steve', 'linus', 'martin', 'dieter', 'ada', 'grace', 'alice', 'ken',
+  'steve', 'linus', 'martin', 'anders', 'dieter', 'ada', 'grace', 'alice', 'ken',
   'margaret', 'shannon', 'alan', 'norman',
   // philosophy / psychology
   'kongzi', 'socrates', 'nietzsche', 'kahneman', 'jung',

package/yeaft/vp/vp-bridge.js

@@ -8,6 +8,7 @@
  *
  * Per ruling §2 (D2):
  *   • subtitle  → agent emits `vp.role` directly
+ *   • capability descriptions → additive localized wire fields
  *   • personaHash → agent emits `vp.personaHash`
  *   • color / avatar → web-derived, NOT emitted here
  *
@@ -194,8 +195,8 @@ function ensureLoader(registry = defaultRegistry, options = {}) {
  * Serialise a VP (entity layer shape) to the wire-format the web layer
  * expects (spec §2.1). Pure; no IO.
  *
- * @param {{id:string,name:string,role:string,nameZh?:string,aliases?:string[],traits?:string[],modelHint?:string,personaHash?:string}} vp
- * @returns {{vpId:string,displayName:string,displayNameZh:string,aliases:string[],subtitle:string,role:string,traits:string[],modelHint:?string,personaHash:?string,isStock:boolean}}
+ * @param {{id:string,name:string,role:string,nameZh?:string,description?:string,descriptionZh?:string,roleZh?:string,aliases?:string[],traits?:string[],modelHint?:string,personaHash?:string}} vp
+ * @returns {{vpId:string,displayName:string,displayNameZh:string,description:string,descriptionZh:string,aliases:string[],subtitle:string,role:string,roleZh:string,traits:string[],modelHint:?string,personaHash:?string,isStock:boolean}}
  */
 export function serializeVpForWire(vp) {
   return {
@@ -204,8 +205,11 @@ export function serializeVpForWire(vp) {
     // task-fix (5-bugs): carry bilingual name + aliases (incl. pinyin) to
     // the frontend so @ mention matching + localised rendering work.
     displayNameZh: typeof vp.nameZh === 'string' ? vp.nameZh : '',
+    description: typeof vp.description === 'string' ? vp.description : '',
+    descriptionZh: typeof vp.descriptionZh === 'string' ? vp.descriptionZh : '',
     aliases: Array.isArray(vp.aliases) ? vp.aliases.slice() : [],
     role: vp.role || '',
+    roleZh: typeof vp.roleZh === 'string' ? vp.roleZh : '',
     subtitle: vp.role || '',
     traits: Array.isArray(vp.traits) ? vp.traits.slice() : [],
     modelHint: vp.modelHint ?? null,

package/yeaft/vp/vp-crud.js

@@ -97,7 +97,7 @@ function vpRolePathFor(libDir, vpId) {
  * Serialise a VP payload into role.md text with YAML frontmatter matching
  * the parser in vp-store.js.
  *
- * @param {{vpId:string, displayName?:string, role?:string, traits?:string[], modelHint?:string, persona?:string}} p
+ * @param {{vpId:string, displayName?:string, displayNameZh?:string, aliases?:string[], description?:string, descriptionZh?:string, role?:string, roleZh?:string, area?:string, traits?:string[], modelHint?:string, persona?:string, planInstruction?:string}} p
  * @returns {string}
  */
 export function buildRoleMd(p) {
@@ -105,6 +105,8 @@ export function buildRoleMd(p) {
   const name = p.displayName != null ? String(p.displayName) : id;
   const nameZh = p.displayNameZh != null ? String(p.displayNameZh) : '';
   const aliases = Array.isArray(p.aliases) ? p.aliases.map(a => String(a)).filter(Boolean) : [];
+  const description = p.description != null ? String(p.description) : '';
+  const descriptionZh = p.descriptionZh != null ? String(p.descriptionZh) : '';
   const role = p.role != null ? String(p.role) : '';
   const roleZh = p.roleZh != null ? String(p.roleZh) : '';
   // Taxonomy bucket. Optional + additive — written only when present so
@@ -116,10 +118,15 @@ export function buildRoleMd(p) {
 
   const lines = ['---', `id: ${id}`, `name: ${yamlScalar(name)}`];
   if (nameZh) lines.push(`nameZh: ${yamlScalar(nameZh)}`);
+  if (description) lines.push(`description: ${yamlScalar(description)}`);
+  if (descriptionZh) lines.push(`descriptionZh: ${yamlScalar(descriptionZh)}`);
   lines.push(`role: ${yamlScalar(role)}`);
   if (roleZh) lines.push(`roleZh: ${yamlScalar(roleZh)}`);
   if (area) lines.push(`area: ${yamlScalar(area)}`);
   if (modelHint) lines.push(`modelHint: ${modelHint}`);
+  if (p.planInstruction != null && String(p.planInstruction)) {
+    lines.push(`planInstruction: ${yamlScalar(String(p.planInstruction))}`);
+  }
   if (traits.length > 0) {
     lines.push('traits:');
     for (const t of traits) lines.push(`  - ${yamlScalar(t)}`);
@@ -134,21 +141,58 @@ export function buildRoleMd(p) {
 
 function yamlScalar(v) {
   const s = String(v);
-  // Quote anything that the minimal parser might mis-read: colons, leading
-  // dashes, or surrounding whitespace. Plain text passes through unquoted.
-  if (/^[\s]|[\s]$|^[-:]|[:#]/.test(s)) {
-    return `"${s.replace(/"/g, '\\"')}"`;
+  // YAML single-quoted scalars keep backslashes and double quotes literal.
+  // Doubling an apostrophe is the only escape, and parseYamlScalar reverses
+  // exactly that operation. This also avoids interpreting legacy Windows
+  // paths such as `C:\temp` as JSON/YAML control escapes.
+  if (/^[\s]|[\s]$|^[-:]|[:#'"\\\n\r\t]/.test(s)) {
+    return `'${s.replace(/'/g, "''")}'`;
   }
   return s;
 }
 
+function hasOwn(obj, key) {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+/**
+ * Merge an update payload with the persisted editable VP shape. Missing keys
+ * mean "old client does not know this field" and must be preserved; an
+ * explicitly supplied empty value remains a deliberate clear operation.
+ */
+function mergeVpUpdate(current, payload, vpId) {
+  const fields = [
+    'displayName',
+    'displayNameZh',
+    'aliases',
+    'description',
+    'descriptionZh',
+    'role',
+    'roleZh',
+    'area',
+    'traits',
+    'modelHint',
+    'persona',
+    'planInstruction',
+  ];
+  const merged = { vpId };
+  for (const field of fields) {
+    merged[field] = hasOwn(payload, field) ? payload[field] : current[field];
+  }
+  return merged;
+}
+
 /**
  * Create a new VP. Writes `<lib>/<vpId>/role.md` and ensures `memory/` dir.
  *
  * @param {object} payload
  * @param {string} payload.vpId
  * @param {string} [payload.displayName]
+ * @param {string} [payload.displayNameZh]
+ * @param {string} [payload.description]
+ * @param {string} [payload.descriptionZh]
  * @param {string} [payload.role]
+ * @param {string} [payload.roleZh]
  * @param {string[]} [payload.traits]
  * @param {'primary'|'fast'} [payload.modelHint]
  * @param {string} [payload.persona]
@@ -208,7 +252,10 @@ export function updateVp(payload, options = {}) {
   if (!existsSync(dir) || !existsSync(vpRolePathFor(libDir, vpId))) {
     throw new VpCrudError('not_found', vpId);
   }
-  writeFileSync(vpRolePathFor(libDir, vpId), buildRoleMd({ ...payload, vpId }), 'utf-8');
+  const current = readVp(vpId, { libDir });
+  if (!current) throw new VpCrudError('not_found', vpId);
+  const merged = mergeVpUpdate(current, payload || {}, vpId);
+  writeFileSync(vpRolePathFor(libDir, vpId), buildRoleMd(merged), 'utf-8');
   return { vpId, dir };
 }
 
@@ -258,7 +305,7 @@ export function deleteVp(vpId, options = {}) {
  *
  * @param {string} vpId
  * @param {object} [options]
- * @returns {?{vpId:string, displayName:string, role:string, traits:string[], modelHint:?string, persona:string}}
+ * @returns {?{vpId:string, displayName:string, displayNameZh:string, aliases:string[], description:string, descriptionZh:string, role:string, roleZh:string, area:string, traits:string[], modelHint:?string, persona:string, planInstruction:string}}
  */
 export function readVp(vpId, options = {}) {
   const libDir = options.libDir || DEFAULT_VP_LIB_DIR;
@@ -279,8 +326,11 @@ export function readVp(vpId, options = {}) {
     displayName: String(meta.name || id),
     displayNameZh: typeof meta.nameZh === 'string' ? String(meta.nameZh) : '',
     aliases: Array.isArray(meta.aliases) ? meta.aliases.map(String) : [],
+    description: typeof meta.description === 'string' ? String(meta.description) : '',
+    descriptionZh: typeof meta.descriptionZh === 'string' ? String(meta.descriptionZh) : '',
     role: String(meta.role || ''),
     roleZh: typeof meta.roleZh === 'string' ? String(meta.roleZh) : '',
+    area: typeof meta.area === 'string' ? String(meta.area).trim() : '',
     traits: Array.isArray(meta.traits) ? meta.traits.map(String) : [],
     modelHint,
     persona: body,

package/yeaft/vp/vp-store.js

@@ -29,7 +29,11 @@ import { createHash } from 'crypto';
  * @typedef {Object} VP
  * @property {string} id              — VP id (default: dir name)
  * @property {string} name
+ * @property {string} nameZh          — optional Chinese display name; '' if absent.
+ * @property {string} description     — concise English capability summary for roster lists.
+ * @property {string} descriptionZh   — optional Chinese capability summary; '' if absent.
  * @property {string} role
+ * @property {string} roleZh          — optional Chinese role label; '' if absent.
  * @property {string} area            — taxonomy bucket (e.g. 'philosophy', 'investing'); '' if absent.
  *                                       Optional, additive: no consumer is required to dispatch on it.
  *                                       Sidebar grouping by area is intentionally a future PR.
@@ -70,6 +74,21 @@ export function personaHash(persona) {
  * @param {string} source
  * @returns {{ meta: Record<string, any>, body: string }}
  */
+function parseYamlScalar(raw) {
+  const value = String(raw || '').trim();
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    // Compatibility for files written by the old CRUD serializer. It escaped
+    // only double quotes, not backslashes, so JSON.parse would corrupt valid
+    // Windows paths (`C:\temp` -> a tab). Undo only the escape the old writer
+    // actually introduced and leave every other backslash literal.
+    return value.slice(1, -1).replace(/\\"/g, '"');
+  }
+  if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1).replace(/''/g, "'");
+  }
+  return value;
+}
+
 export function parseRoleMd(source) {
   const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
   if (!match) return { meta: {}, body: source };
@@ -84,7 +103,7 @@ export function parseRoleMd(source) {
     if (!line.trim()) continue;
     const listMatch = line.match(/^\s+-\s+(.+?)\s*$/);
     if (listMatch && currentList) {
-      currentList.push(listMatch[1].replace(/^['"]|['"]$/g, ''));
+      currentList.push(parseYamlScalar(listMatch[1]));
       continue;
     }
     const kvMatch = line.match(/^([\w-]+):\s*(.*)$/);
@@ -95,7 +114,7 @@ export function parseRoleMd(source) {
         currentList = [];
         meta[key] = currentList;
       } else {
-        meta[key] = value.replace(/^['"]|['"]$/g, '');
+        meta[key] = parseYamlScalar(value);
         currentList = null;
       }
     }
@@ -156,6 +175,8 @@ export function loadVpFromDir(dir) {
     aliases: Array.isArray(meta.aliases)
       ? meta.aliases.map(String).map(s => s.trim()).filter(Boolean)
       : [],
+    description: typeof meta.description === 'string' ? String(meta.description) : '',
+    descriptionZh: typeof meta.descriptionZh === 'string' ? String(meta.descriptionZh) : '',
     role: String(meta.role || ''),
     roleZh: typeof meta.roleZh === 'string' ? String(meta.roleZh) : '',
     // Taxonomy bucket for sidebar grouping / filtering. Absent for legacy

package/yeaft/work-center/bridge.js

@@ -66,6 +66,8 @@ async function getSettingsRuntime() {
       id: vp.id,
       name: vp.name || vp.id,
       nameZh: vp.nameZh || '',
+      description: vp.description || vp.role || '',
+      descriptionZh: vp.descriptionZh || vp.roleZh || vp.description || vp.role || '',
       role: vp.role || '',
       roleZh: vp.roleZh || '',
       area: vp.area || '',

package/yeaft/work-center/planner.js

@@ -6,6 +6,8 @@ function publicVp(vp) {
     id: vp.id,
     name: vp.name || vp.id,
     nameZh: vp.nameZh || '',
+    description: vp.description || vp.role || '',
+    descriptionZh: vp.descriptionZh || vp.roleZh || vp.description || vp.role || '',
     role: vp.role || '',
     roleZh: vp.roleZh || '',
     area: vp.area || '',