@waterplus-ai/waterbuddy 0.1.78 → 0.2.5

package/lib/host/experts.js

@@ -1,10 +1,11 @@
 /**
- * 专家名册：把 `assets/experts/<分区>/<slug>.md` 读成可召唤的专家目录。
+ * 专家名册：把旧版 Markdown persona 与 ntd 目录包统一读成可召唤的专家目录。
  *
- * 每份 persona 的正文是**完整的系统提示词**（十几 KB 量级），所以启动时只读
- * frontmatter 做目录，正文留到真正召唤时再读（见 `readExpertPersona`）。
+ * 旧版 persona 仍支持 `assets/experts/<分区>/<slug>.md`；新目录包使用
+ * `.codebuddy-plugin/plugin.json` 与 `agents/*.md`。每份 persona 的正文是**完整的系统提示词**，
+ * 所以启动时只读 frontmatter/元数据做目录，正文留到真正召唤时再读。
  *
- * 文件格式（frontmatter + 正文，正文即系统提示词）：
+ * 旧版文件格式（frontmatter + 正文，正文即系统提示词）：
  *
  *     ---
  *     name: 供水管网水力建模专家
@@ -18,6 +19,7 @@
  * 这样解析器不需要引入 YAML 依赖——本插件是零依赖的纯 JS 包。
  */
 import fs from 'node:fs/promises'
+import os from 'node:os'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -124,6 +126,42 @@ export function parseExpertFrontmatter(text) {
   return {}
 }
 
+function parseFrontmatterCollections(text) {
+  const lines = stripBom(String(text)).split(/\r?\n/)
+  if (lines[0]?.trim() !== '---') return {}
+  const collections = {}
+  let currentKey = ''
+  let currentItem
+  for (const line of lines.slice(1)) {
+    if (line.trim() === '---') break
+    const section = line.match(/^([A-Za-z][\w-]*):\s*$/)
+    if (section) {
+      currentKey = section[1]
+      currentItem = undefined
+      collections[currentKey] = []
+      continue
+    }
+    const item = line.match(/^\s+-\s+(.*)$/)
+    if (item && currentKey) {
+      const value = item[1].trim()
+      if (value.includes(':')) {
+        const separator = value.indexOf(':')
+        currentItem = { [value.slice(0, separator).trim()]: value.slice(separator + 1).trim() }
+        collections[currentKey].push(currentItem)
+      } else {
+        currentItem = value
+        collections[currentKey].push(value)
+      }
+      continue
+    }
+    const property = line.match(/^\s{4,}([A-Za-z][\w-]*):\s*(.*)$/)
+    if (property && currentItem && typeof currentItem === 'object') {
+      currentItem[property[1]] = property[2].trim()
+    }
+  }
+  return collections
+}
+
 /** 去掉 frontmatter，返回正文。 */
 export function expertBody(text) {
   const lines = stripBom(String(text)).split(/\r?\n/)
@@ -134,6 +172,141 @@ export function expertBody(text) {
   return ''
 }
 
+const NTD_PLUGIN_DIR = '.codebuddy-plugin'
+const NTD_PLUGIN_FILE = 'plugin.json'
+
+async function readJsonFile(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'))
+  } catch (error) {
+    if (error.code === 'ENOENT') return undefined
+    throw new Error(`EXPERT_PLUGIN_INVALID: ${filePath} 无法解析 plugin.json`)
+  }
+}
+
+function ntdSlug(values) {
+  for (const value of values) {
+    const slug = String(value || '').trim().toLowerCase()
+    if (EXPERT_PATH_SEGMENT_PATTERN.test(slug)) return slug
+  }
+  return ''
+}
+
+function ntdLocalized(value) {
+  if (value && typeof value === 'object') {
+    return String(value.zh || value.en || Object.values(value)[0] || '').trim()
+  }
+  return String(value || '').trim()
+}
+
+function ntdMember(member) {
+  if (typeof member === 'string') return { slug: member, name: member, avatar: '' }
+  if (!member || typeof member !== 'object') return undefined
+  const slug = String(member.slug || member.id || ntdLocalized(member.name) || '').trim()
+  if (!slug) return undefined
+  return {
+    slug,
+    name: ntdLocalized(member.displayName || member.name || slug),
+    avatar: String(member.avatar || '').trim(),
+  }
+}
+
+async function loadNtdEntry(directory, pluginPath) {
+  const plugin = await readJsonFile(pluginPath)
+  if (!plugin || typeof plugin !== 'object') return undefined
+  const isTeam = String(plugin.expertType || '').toLowerCase() === 'team'
+  const fallback = path.basename(directory)
+  const configuredSlug = plugin.slug || plugin.name
+  const slug = ntdSlug([configuredSlug || fallback])
+  if (!slug) throw new Error(`EXPERT_SLUG_INVALID: ${directory} 的 plugin.json name 不合法`)
+  const agentsDir = path.join(directory, 'agents')
+  let agentFiles = []
+  try { agentFiles = (await fs.readdir(agentsDir)).filter(file => file.endsWith('.md')).sort() } catch (error) { if (error.code !== 'ENOENT') throw error }
+  const teamInfo = plugin.teamInfo && typeof plugin.teamInfo === 'object' ? plugin.teamInfo : {}
+  const declaredAgents = Array.isArray(plugin.agents) ? plugin.agents : []
+  const leadRef = isTeam
+    ? String(teamInfo.leadAgent || teamInfo.leader || teamInfo.lead || plugin.agentName || agentFiles[0] || declaredAgents[0] || '').trim()
+    : String(plugin.agent || plugin.agentName || agentFiles[0] || declaredAgents[0] || '').trim()
+  const leadPath = leadRef.includes('/') ? leadRef : path.join('agents', leadRef.endsWith('.md') ? leadRef : `${leadRef}.md`)
+  const leadFile = leadRef
+    ? path.resolve(directory, leadPath)
+    : undefined
+  if (!leadFile || !leadFile.startsWith(path.resolve(directory) + path.sep)) throw new Error(`EXPERT_AGENT_INVALID: ${slug} 的负责人路径不合法`)
+  let leadFields = {}
+  try {
+    leadFields = parseExpertFrontmatter(await readFrontmatterHead(leadFile))
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new Error(`EXPERT_AGENT_MISSING: ${slug} 找不到负责人文件 ${leadRef}`)
+    throw error
+  }
+  const displayName = ntdLocalized(plugin.displayName || plugin.title || leadFields.displayName || leadFields.name || (plugin.name && !EXPERT_PATH_SEGMENT_PATTERN.test(String(plugin.name).trim()) ? plugin.name : slug))
+  const description = ntdLocalized(plugin.description || plugin.displayDescription || plugin.summary || leadFields.description || '水务行业专家')
+  if (!displayName || !description) throw new Error(`EXPERT_FRONTMATTER_INCOMPLETE: ${directory} 缺少 displayName 或 description`)
+  const declaredMembers = Array.isArray(teamInfo.members) && teamInfo.members.length > 0
+    ? teamInfo.members
+    : Array.isArray(plugin.members)
+      ? [...plugin.members, ...(Array.isArray(teamInfo.memberAgents)
+        ? teamInfo.memberAgents
+          .filter(member => !plugin.members.some(item => item && (item.id === member || item.slug === member)))
+          .map(member => ({ id: member }))
+        : [])]
+      : Array.isArray(teamInfo.memberAgents)
+        ? teamInfo.memberAgents
+        : []
+  const members = isTeam ? declaredMembers.map(ntdMember).filter(Boolean) : []
+  return {
+    slug,
+    name: displayName,
+    description,
+    version: String(plugin.version || '').trim(),
+    profession: ntdLocalized(plugin.profession || ''),
+    displayName: ntdLocalized(plugin.displayName || ''),
+    displayDescription: ntdLocalized(plugin.displayDescription || ''),
+    defaultInitPrompt: ntdLocalized(plugin.defaultInitPrompt || ''),
+    quickPrompts: Array.isArray(plugin.quickPrompts) ? plugin.quickPrompts.map(item => ntdLocalized(item)).filter(Boolean) : [],
+    tags: Array.isArray(plugin.tags)
+      ? plugin.tags.map(item => ({
+        zh: ntdLocalized(item && typeof item === 'object' ? item.zh : item),
+        en: ntdLocalized(item && typeof item === 'object' ? item.en : item),
+      })).filter(item => item.zh || item.en)
+      : [],
+    categoryId: String(plugin.categoryId || '').trim(),
+    agentName: String(plugin.agentName || plugin.agent_name || '').trim(),
+    leadAgent: String(teamInfo.leadAgent || teamInfo.leader || '').trim(),
+    memberAgents: Array.isArray(teamInfo.memberAgents) ? teamInfo.memberAgents.map(String) : [],
+    emoji: String(plugin.emoji || leadFields.emoji || (isTeam ? '👥' : '🧠')).trim(),
+    avatar: String(plugin.avatar || leadFields.avatar || '').trim(),
+    filePath: leadFile,
+    custom: false,
+    source: 'ntd',
+    kind: isTeam ? 'team' : 'expert',
+    expertType: isTeam ? 'team' : 'expert',
+    members,
+    skills: Array.isArray(plugin.skills) ? plugin.skills : [],
+    pluginPath,
+    assetDir: directory,
+    plugin,
+  }
+}
+
+async function walkNtdEntries(directory, add, division, depth = 0) {
+  if (depth > 4) return
+  let entries
+  try { entries = await fs.readdir(directory, { withFileTypes: true }) } catch (error) { if (error.code === 'ENOENT') return; throw error }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const child = path.join(directory, entry.name)
+    const pluginPath = path.join(child, NTD_PLUGIN_DIR, NTD_PLUGIN_FILE)
+    const plugin = await loadNtdEntry(child, pluginPath)
+    if (plugin) {
+      if (plugin.kind !== 'team') plugin.division = division || 'general'
+      add(plugin)
+    } else {
+      await walkNtdEntries(child, add, division || entry.name, depth + 1)
+    }
+  }
+}
+
 /**
  * 扫描名册目录，只读 frontmatter 建立目录。
  *
@@ -141,41 +314,66 @@ export function expertBody(text) {
  * 专家在分区内按 slug 排序，保证同一次构建的目录顺序稳定。
  *
  * @param rootDir - 名册根目录，默认 {@link DEFAULT_EXPERTS_DIR}。
- * @returns `{ divisions, bySlug }`；`divisions` 是 `[{ slug, name, experts }]`。
+ * @returns `{ divisions, teams, bySlug }`；`divisions` 是 `[{ slug, name, experts }]`。
  * @throws 当文件名不合法、缺必填字段或 slug 重复时——名册是自己发布的资产，
  *   坏文件必须显式失败，不能悄悄少一个专家。
  */
 export async function loadExpertCatalog(rootDir = DEFAULT_EXPERTS_DIR) {
   const divisions = []
   const bySlug = new Map()
+  const teams = []
+  const seenNtdPlugins = new Set()
+  const byDivision = new Map()
+  const add = expert => {
+    if (bySlug.has(expert.slug)) throw new Error(`EXPERT_SLUG_DUPLICATE: ${expert.slug} 在名册中重复`)
+    bySlug.set(expert.slug, expert)
+    if (expert.kind === 'team') {
+      teams.push(expert)
+      return
+    }
+    const divisionSlug = expert.division || 'general'
+    let division = byDivision.get(divisionSlug)
+    if (!division) {
+      division = { slug: divisionSlug, name: EXPERT_DIVISIONS[divisionSlug] || divisionSlug, experts: [] }
+      byDivision.set(divisionSlug, division)
+      divisions.push(division)
+    }
+    division.experts.push(expert)
+  }
   let divisionEntries = []
   try {
     divisionEntries = await fs.readdir(rootDir, { withFileTypes: true })
   } catch (error) {
-    if (error.code === 'ENOENT') return { divisions, bySlug }
+    if (error.code === 'ENOENT') return { divisions, teams, bySlug }
     throw error
   }
 
   for (const entry of divisionEntries) {
     if (!entry.isDirectory() || !EXPERT_PATH_SEGMENT_PATTERN.test(entry.name)) continue
     const divisionSlug = entry.name
-    const experts = []
-    const files = (await fs.readdir(path.join(rootDir, divisionSlug))).filter(name => name.endsWith('.md')).sort()
+    const divisionDir = path.join(rootDir, divisionSlug)
+    const ntdPlugin = await loadNtdEntry(divisionDir, path.join(divisionDir, NTD_PLUGIN_DIR, NTD_PLUGIN_FILE))
+    if (ntdPlugin) {
+      seenNtdPlugins.add(ntdPlugin.pluginPath)
+      if (ntdPlugin.kind !== 'team') ntdPlugin.division = divisionSlug
+      add(ntdPlugin)
+      continue
+    }
+    const files = (await fs.readdir(divisionDir)).filter(name => name.endsWith('.md')).sort()
     for (const file of files) {
       const slug = file.slice(0, -3)
       if (!EXPERT_PATH_SEGMENT_PATTERN.test(slug)) {
         throw new Error(`EXPERT_SLUG_INVALID: ${divisionSlug}/${file} 只允许小写字母数字与连字符`)
       }
       const filePath = path.join(rootDir, divisionSlug, file)
-      const fields = parseExpertFrontmatter(await readFrontmatterHead(filePath))
+      const header = await readFrontmatterHead(filePath)
+      const fields = parseExpertFrontmatter(header)
+      const collections = parseFrontmatterCollections(header)
       const name = (fields.name || '').trim()
       const description = (fields.description || '').trim()
       if (!name || !description) {
         throw new Error(`EXPERT_FRONTMATTER_INCOMPLETE: ${divisionSlug}/${file} 缺少 name 或 description`)
       }
-      if (bySlug.has(slug)) {
-        throw new Error(`EXPERT_SLUG_DUPLICATE: ${slug} 在名册中重复`)
-      }
       if (fields.division && fields.division !== divisionSlug) {
         throw new Error(
           `EXPERT_DIVISION_MISMATCH: ${divisionSlug}/${file} 的 division=${fields.division} 与目录不一致`,
@@ -186,26 +384,46 @@ export async function loadExpertCatalog(rootDir = DEFAULT_EXPERTS_DIR) {
         division: divisionSlug,
         name,
         description,
+        version: String(fields.version || '').trim(),
+        profession: String(fields.profession || '').trim(),
+        displayName: String(fields.displayName || '').trim(),
+        displayDescription: String(fields.displayDescription || '').trim(),
+        defaultInitPrompt: String(fields.defaultInitPrompt || '').trim(),
+        quickPrompts: String(fields.quickPrompts || '').split('|').map(item => item.trim()).filter(Boolean),
+        tags: String(fields.tags || '').split('|').map(item => item.trim()).filter(Boolean).map(item => ({ zh: item, en: item })),
+        categoryId: String(fields.categoryId || '').trim(),
+        frontmatter: fields,
+        knowledgeBases: Array.isArray(collections.knowledgeBases) ? collections.knowledgeBases : [],
         emoji: (fields.emoji || '').trim(),
         // 头像图片：http(s) URL 直接用；否则当作与本 md 同目录的文件名，
         // 由 `/api/waterbuddy/experts/avatar` 按需吐出来（不塞进名册快照）。
         avatar: (fields.avatar || '').trim(),
         filePath,
         custom: false,
+        source: 'legacy',
+        kind: 'expert',
+        expertType: 'expert',
+        members: [],
       }
-      experts.push(expert)
-      bySlug.set(slug, expert)
-    }
-    if (experts.length > 0) {
-      divisions.push({
-        slug: divisionSlug,
-        name: EXPERT_DIVISIONS[divisionSlug] || divisionSlug,
-        experts,
-      })
+      add(expert)
     }
   }
 
-  return { divisions, bySlug }
+  await walkNtdEntries(rootDir, expert => {
+    if (seenNtdPlugins.has(expert.pluginPath)) return
+    seenNtdPlugins.add(expert.pluginPath)
+    add(expert)
+  }, undefined)
+  // NTD 团队只保存成员引用；等所有旧版与 NTD 专家都入册后再解析，避免目录顺序影响结果。
+  for (const team of teams) {
+    team.memberExperts = team.members.map(member => bySlug.get(member.slug)).filter(Boolean)
+  }
+  // 声明顺序优先，未知分区稳定排在最后；避免 readdir 顺序改变设置页和 @ 菜单。
+  const divisionOrder = new Map(Object.keys(EXPERT_DIVISIONS).map((slug, index) => [slug, index]))
+  divisions.sort((left, right) => (divisionOrder.get(left.slug) ?? Number.MAX_SAFE_INTEGER) - (divisionOrder.get(right.slug) ?? Number.MAX_SAFE_INTEGER) || left.slug.localeCompare(right.slug))
+  for (const division of divisions) division.experts.sort((left, right) => left.slug.localeCompare(right.slug))
+  teams.sort((left, right) => left.slug.localeCompare(right.slug))
+  return { divisions, teams, bySlug }
 }
 
 /**
@@ -223,6 +441,178 @@ export async function readExpertBody(expert) {
   return expertBody(await fs.readFile(expert.filePath, 'utf8'))
 }
 
+async function countExpertFilesAndSize(target) {
+  let fileCount = 0
+  let totalSize = 0
+  const walk = async current => {
+    const stat = await fs.stat(current).catch(() => undefined)
+    if (!stat) return
+    if (stat.isFile()) {
+      fileCount += 1
+      totalSize += stat.size
+      return
+    }
+    if (!stat.isDirectory()) return
+    const entries = await fs.readdir(current, { withFileTypes: true })
+    for (const entry of entries) {
+      if (entry.name === '.git') continue
+      await walk(path.join(current, entry.name))
+    }
+  }
+  await walk(target)
+  return { fileCount, totalSize }
+}
+
+function displayExpertPath(target) {
+  const absolute = path.resolve(target)
+  const home = os.homedir()
+  if (absolute === home) return '~'
+  if (absolute.startsWith(home + path.sep)) return '~' + absolute.slice(home.length)
+  const relative = path.relative(process.cwd(), absolute)
+  return relative && !relative.startsWith('..') ? relative : absolute
+}
+
+function detailAgentName(filePath) {
+  return path.basename(filePath).replace(/\.md$/i, '')
+}
+
+function detailAgentMatches(agent, wanted) {
+  if (!wanted) return false
+  const normalized = String(wanted).replace(/^\.\//, '')
+  return agent.name === wanted
+    || agent.relPath.replace(/^\.\//, '') === normalized
+    || detailAgentName(agent.relPath) === detailAgentName(normalized)
+}
+
+async function readAgentDetails(expert) {
+  if (expert.custom && !expert.filePath) return []
+  if (expert.source !== 'ntd') {
+    const relPath = expert.filePath ? path.basename(expert.filePath) : `${expert.slug}.md`
+    return [{
+      name: expert.name || expert.slug,
+      description: expert.description || '',
+      emoji: expert.emoji || '',
+      relPath,
+      role: 'lead',
+    }]
+  }
+  const root = expert.assetDir
+  if (!root) return []
+  let relativePaths = Array.isArray(expert.plugin?.agents) ? expert.plugin.agents.map(String) : []
+  if (relativePaths.length === 0) {
+    try {
+      relativePaths = (await fs.readdir(path.join(root, 'agents'), { withFileTypes: true }))
+        .filter(entry => entry.isFile() && entry.name.endsWith('.md'))
+        .map(entry => `./agents/${entry.name}`)
+        .sort()
+    } catch {
+      relativePaths = []
+    }
+  }
+  const details = []
+  for (const relPath of relativePaths) {
+    const filePath = path.resolve(root, relPath)
+    if (!(filePath === path.resolve(root) || filePath.startsWith(path.resolve(root) + path.sep))) continue
+    const fields = await readFrontmatterHead(filePath).then(parseExpertFrontmatter).catch(() => ({}))
+    const fileName = detailAgentName(filePath)
+    const member = (expert.members || []).find(item => detailAgentMatches({ name: item.slug, relPath: fileName }, fileName) || item.slug === fileName)
+    details.push({
+      name: String(fields.name || fields.displayName || fileName).trim(),
+      description: String(fields.description || '').trim(),
+      emoji: String(fields.emoji || '').trim(),
+      relPath,
+      role: member?.role || (detailAgentMatches({ name: fileName, relPath }, expert.leadAgent || expert.agentName) ? 'lead' : 'member'),
+    })
+  }
+  return details
+}
+
+async function readSkillDetails(expert) {
+  const skills = Array.isArray(expert.plugin?.skills) ? expert.plugin.skills : (expert.skills || [])
+  if (!Array.isArray(skills) || skills.length === 0) return []
+  const root = expert.assetDir
+  const details = []
+  for (const item of skills) {
+    const raw = typeof item === 'string' ? item : item?.name || item?.path || ''
+    const relPath = String(raw || '').trim()
+    if (!relPath) continue
+    if (!root) {
+      details.push({ skillName: relPath, description: '', descriptionZh: '', descriptionEn: '' })
+      continue
+    }
+    const skillDir = path.resolve(root, relPath)
+    if (!(skillDir === path.resolve(root) || skillDir.startsWith(path.resolve(root) + path.sep))) continue
+    const skillPath = path.join(skillDir, 'SKILL.md')
+    const fields = await readFrontmatterHead(skillPath).then(parseExpertFrontmatter).catch(() => ({}))
+    const skillName = String(fields.name || path.basename(skillDir)).trim()
+    details.push({
+      skillName,
+      description: String(fields.description || '').trim(),
+      descriptionZh: String(fields.description_zh || fields.description || '').trim(),
+      descriptionEn: String(fields.description_en || '').trim(),
+      version: String(fields.version || '').trim(),
+      emoji: String(fields.emoji || '').trim(),
+      relPath,
+    })
+  }
+  return details
+}
+
+/**
+ * 读取设置页详情弹窗所需的完整元数据。
+ *
+ * 名册快照保持轻量；只有用户打开详情时才读取目录统计、agent 摘要、技能摘要和 plugin.json。
+ */
+export async function readExpertDetails(expert) {
+  const root = expert.assetDir || expert.filePath || ''
+  const stats = root ? await countExpertFilesAndSize(root) : { fileCount: 0, totalSize: 0 }
+  const agents = await readAgentDetails(expert)
+  const pluginMembers = Array.isArray(expert.plugin?.members) ? expert.plugin.members : []
+  const members = (expert.members || []).map(member => {
+    const metadata = pluginMembers.find(item => item && (item.id === member.slug || item.slug === member.slug))
+    return {
+      ...member,
+      profession: metadata ? ntdLocalized(metadata.profession || metadata.roleName || '') : '',
+      role: metadata?.role === 'lead' ? 'lead' : (member.slug === (expert.leadAgent || expert.agentName) ? 'lead' : 'member'),
+    }
+  })
+  const pluginJson = expert.source === 'ntd'
+    ? (expert.plugin || {})
+    : {
+      name: expert.slug,
+      version: expert.version || '1.0.0',
+      expertType: 'agent',
+      displayName: { zh: expert.name },
+      profession: { zh: expert.profession || expert.name },
+      displayDescription: { zh: expert.description },
+      agentName: expert.slug,
+      ...(expert.frontmatter || {}),
+    }
+  const leadAgent = expert.leadAgent || expert.agentName || agents[0]?.name || ''
+  const leadAgentFile = agents.find(agent => detailAgentMatches(agent, leadAgent))?.relPath || agents[0]?.relPath || ''
+  const quickPrompts = Array.isArray(expert.quickPrompts) ? expert.quickPrompts : []
+  return {
+    source: expert.custom ? 'user' : 'builtin',
+    sourceLabel: expert.custom ? '自定义' : '内置',
+    readOnly: expert.custom !== true,
+    version: expert.version || pluginJson.version || '1.0.0',
+    profession: expert.profession || ntdLocalized(pluginJson.profession || ''),
+    defaultInitPrompt: expert.defaultInitPrompt || ntdLocalized(pluginJson.defaultInitPrompt || ''),
+    quickPrompts,
+    tags: expert.tags || [],
+    knowledgeBases: expert.knowledgeBases || (Array.isArray(pluginJson.knowledgeBases) ? pluginJson.knowledgeBases : []),
+    categoryId: expert.categoryId || String(pluginJson.categoryId || '').trim(),
+    dir: displayExpertPath(root),
+    fileCount: stats.fileCount,
+    totalSize: stats.totalSize,
+    members,
+    agentFiles: agents,
+    leadAgentFile,
+    skillMeta: await readSkillDetails(expert),
+    pluginJson,
+  }
+}
+
 /**
  * 把自定义专家并进内置名册，产出一份新名册（不改原对象）。
  *
@@ -237,6 +627,7 @@ export function mergeCustomExperts(catalog, customExperts) {
   if (!Array.isArray(customExperts) || customExperts.length === 0) return catalog
   const bySlug = new Map(catalog.bySlug)
   const divisions = catalog.divisions.map(division => ({ ...division, experts: [...division.experts] }))
+  const teams = [...(catalog.teams || [])]
   const byDivision = new Map(divisions.map(division => [division.slug, division]))
   for (const custom of customExperts) {
     if (!custom || bySlug.has(custom.slug)) continue
@@ -249,6 +640,10 @@ export function mergeCustomExperts(catalog, customExperts) {
       avatar: custom.avatar || '',
       body: custom.prompt,
       custom: true,
+      source: 'user',
+      kind: 'expert',
+      expertType: 'expert',
+      members: [],
     }
     bySlug.set(expert.slug, expert)
     const division = byDivision.get(expert.division)
@@ -264,7 +659,7 @@ export function mergeCustomExperts(catalog, customExperts) {
       divisions.push(created)
     }
   }
-  return { divisions, bySlug }
+  return { divisions, teams, bySlug }
 }
 
 /**
@@ -298,7 +693,86 @@ export const EXPERT_OUTPUT_RULES = [
  */
 export async function readExpertPersona(expert) {
   const body = await readExpertBody(expert)
-  return sanitizePersona(`${EXPERT_OUTPUT_RULES}\n${body}`)
+  const teamContext = expert.kind === 'team'
+    ? [
+      '## 专家团协作上下文',
+      '',
+      '你是一个专家团的负责人。以下成员是可协同的专业角色；请在最终交付中综合成员视角，',
+      '不要虚构未提供的成员结论，也不要把内部协作过程写进给用户的成品。',
+      ...(expert.members || []).map(member => `- ${member.name || member.slug}（${member.slug}）`),
+      '',
+    ].join('\n')
+    : ''
+  return sanitizePersona(`${EXPERT_OUTPUT_RULES}\n${teamContext}${body}`)
+}
+
+function normalizeAgentReference(value) {
+  return String(value || '')
+    .replaceAll('\\', '/')
+    .replace(/^\.\//, '')
+    .replace(/^agents\//, '')
+    .replace(/\.md$/i, '')
+    .trim()
+}
+
+function teamMemberMetadata(expert, memberId) {
+  const wanted = normalizeAgentReference(memberId)
+  return (expert.members || []).find(member => normalizeAgentReference(member.slug) === wanted)
+    || (expert.members || []).find(member => normalizeAgentReference(member.name) === wanted)
+}
+
+async function resolveTeamMemberFile(expert, memberId) {
+  const wanted = normalizeAgentReference(memberId)
+  if (!wanted || !expert?.assetDir) return undefined
+  const root = path.resolve(expert.assetDir)
+  const candidates = []
+  if (expert.filePath) candidates.push(expert.filePath)
+  const configuredAgents = Array.isArray(expert.plugin?.agents) ? expert.plugin.agents : []
+  for (const configured of configuredAgents) {
+    const relative = String(configured || '').trim()
+    if (relative) candidates.push(path.resolve(root, relative))
+  }
+  for (const candidate of candidates) {
+    const absolute = path.resolve(candidate)
+    if (!(absolute === root || absolute.startsWith(root + path.sep))) continue
+    const relative = path.relative(root, absolute)
+    if (normalizeAgentReference(relative) !== wanted && normalizeAgentReference(path.basename(absolute)) !== wanted) continue
+    try {
+      const stat = await fs.stat(absolute)
+      if (stat.isFile()) return absolute
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error
+    }
+  }
+  return undefined
+}
+
+/**
+ * 读取专家团中某一成员的完整 persona。
+ *
+ * 成员可以是 NTD 包内的 `agents/*.md`，也可以是旧名册中由团队引用的专家。
+ * 这个 helper 只给 Host 的 fan-out 使用；详情页仍然读取未消毒的原文。
+ */
+export async function readExpertMemberPersona(expert, memberId) {
+  if (expert?.kind !== 'team') return readExpertPersona(expert)
+  const member = teamMemberMetadata(expert, memberId)
+  const localFile = await resolveTeamMemberFile(expert, memberId)
+  let body
+  if (localFile) {
+    body = expertBody(await fs.readFile(localFile, 'utf8'))
+  } else {
+    const referenced = (expert.memberExperts || []).find(item => normalizeAgentReference(item.slug) === normalizeAgentReference(memberId))
+    if (!referenced) throw new Error(`EXPERT_MEMBER_PERSONA_MISSING: ${expert.slug}/${memberId}`)
+    body = await readExpertBody(referenced)
+  }
+  if (!body) throw new Error(`EXPERT_MEMBER_PERSONA_EMPTY: ${expert.slug}/${memberId}`)
+  const teamContext = [
+    '## 专家团协作上下文',
+    '',
+    `你是“${expert.name}”中的${member?.name || memberId}。只输出自己的专业判断，供负责人汇总；不要虚构其他成员结论。`,
+    '',
+  ].join('\n')
+  return sanitizePersona(`${EXPERT_OUTPUT_RULES}\n${teamContext}${body}`)
 }
 
 /**
@@ -313,6 +787,17 @@ export function resolveExpertAvatar(expert) {
   if (!raw) return undefined
   if (/^https?:\/\//i.test(raw)) return { kind: 'remote', url: raw }
   if (raw.includes('..') || raw.startsWith('/')) return undefined
-  if (!expert.filePath) return undefined
-  return { kind: 'file', path: path.join(path.dirname(expert.filePath), raw) }
+  if (!expert.filePath && !expert.assetDir) return undefined
+  const baseDir = expert.assetDir || path.dirname(expert.filePath)
+  return { kind: 'file', path: path.join(baseDir, raw) }
+}
+
+export function resolveExpertMemberAvatar(expert, member) {
+  const raw = String(member?.avatar || '').trim()
+  if (!raw) return undefined
+  if (/^https?:\/\//i.test(raw)) return { kind: 'remote', url: raw }
+  if (raw.includes('..') || raw.startsWith('/')) return undefined
+  if (!expert?.filePath && !expert?.assetDir) return undefined
+  const baseDir = expert.assetDir || path.dirname(expert.filePath)
+  return { kind: 'file', path: path.join(baseDir, raw) }
 }