专家角色(dsh-expert-role)
中文 · English
把领域知识做成随用随取的专家库:一个目录一位专家,模型按需加载,每次读取都留痕。
模型的知识不覆盖新领域(AI 生图、短剧、某个内部工具),资料又散在几十个文件夹里。这个插件把「一个领域的资料 + 调研过程」收成一位专家,注册成技能;模型平时只看到一行简介,真正需要时再读正文和引用文件。读过什么、什么时候读的,都写进调用记录。
三步上手
- 装插件、重启 DSH,左侧菜单多出「专家库」。
- 在对话里说「帮我建一个 AI 生图专家,把
D:\调研\生图这些资料整理进去」——模型会建骨架、把资料搬进来、登记成技能。 - 需要时直接问;模型按「调用方式」(默认:你点名才查)决定要不要加载这位专家。界面可在「设置 → 界面语言」里切成 English。
插件只做三件事:把资料变成可加载的技能、把调研过程写进同一个目录、把每次读取记下来。
安装
git clone https://github.com/yjnmedia/dsh-expert-role.git
cd dsh-expert-role
dsh plugin --profile desktop add .
Windows(PowerShell)同样三条命令,最后一行一样。
装完重启 DSH,左侧菜单的入口列表里会多一项「专家库」。它插在菜单已有入口之间,具体位置取决于你还装了哪些插件——认名字即可。插件针对 DSH 0.2 系列开发。
先指一个专家库目录
专家库就是一个普通文件夹,插件从环境变量 DSH_EXPERT_ROOT 读它的位置:
# Windows,永久生效
setx DSH_EXPERT_ROOT "D:\AIExperts"
# macOS / Linux
export DSH_EXPERT_ROOT="$HOME/AIExperts"
不设的话,默认用用户主目录下的 AIExperts(Windows 上是 C:\Users\<你的用户名>\AIExperts,macOS / Linux 上是 ~/AIExperts)。第一次打开面板能看到当前用的是哪个路径。
建第一位专家
在对话里直接说:
帮我建一个「AI 生图」专家,把
D:\调研\生图下这些资料整理进去。
模型会调 expert_create 生成骨架,再用 expert_ingest 把每份资料搬进专家库并登记。不需要你自己拼目录。
落下来是这样(资料本体在专家目录里,不在别处留副本):
<DSH_EXPERT_ROOT>/
└── ai-image/
├── SKILL.md # 名称、简介、正文(模型真正读到的部分)
├── manifest.json # 标题、状态、调研模式、主题与资料清单
├── references/ # 所有资料,按主题分节
│ ├── index.md # 资料索引(资料名 / 路径 / 一句话)
│ ├── prompt-weighting_20261113/ # 一份资料一个英文目录
│ └── ...
├── 资料对照.md # 中文名 ↔ 英文目录
├── 资料快捷方式/ # 中文名 .lnk,双击直达英文目录
└── survey.md # 尽调计划 + 步骤 + 进度记录
为什么目录名是英文:中文目录在 PowerShell / MSYS / Python 之间来回搬时会被按错误编码读写,本机就出过一次乱码目录。中文名不丢——它写在 manifest.json 的 title、references/index.md 和 资料对照.md 里,面板也按中文显示。
SKILL.md 的 frontmatter 至少要有 name 和 description;正文控制在 8K 字符以内,细节放 references/。
把一段旧资料搬进来
expert_ingest({ expert: "ai-image", source: "D:\\调研\\生图\\提示词调研" })
- 只强制
expert和source,目录或单个文件都行; - 资料会被移动到
references/<英文目录>/,原位置不再保留;留一张README.md说明搬到哪里,读到它的会话会被提示来查专家库; - 标题、主题、一句话、什么时候用会从正文推断,推断出来的标「自动推断,可改」;想指定就传
title/topic/slug。
功能
| 能力 | 说明 |
|---|---|
| 专家即技能 | 每位专家注册成 expert-<id>,出现在模型可见的技能目录里,按需加载 |
| 尽调工作流 | 计划、按步记录、并行派子智能体、独立工作区,进度写回 survey.md,可随时续跑 |
| 说人话的面板 | 左栏「专家库」:这位专家会什么、按什么主题找资料、最近被哪个会话用过 |
| 成熟度标记 | 前四颗星只看资料本身(起步 / 可用 / 可靠 / 权威),第五颗星「标杆」才要求真的被用过;点开能看到「为什么是这个星级、怎么补」 |
| 主动调用 | 三档可切(见下「调用方式」):自动识别 / 只在点名时查(默认) / 完全不主动调用 |
| 会话内徽标 | 模型加载专家技能或读资料时,对话里出现一行 📚 专家:ai-image · 读 references/01-提示词.md(12K 字) |
| 调用留痕 | <根>/.trace/trace.jsonl 记录每次 skill_load / ref_read / write / plan / subagent |
工具
| 工具 | 用途 |
|---|---|
expert_list |
列出专家库现状 |
expert_create |
新建专家骨架(不覆盖已有目录) |
expert_plan |
写尽调计划:目标 + 步骤 + 模式(parallel / serial / workspace) |
expert_record |
记录某一步的结论,可同时打勾 |
expert_dispatch |
真并行派发:每个未完成步骤各建一个子会话跑,跑完自动记回 survey.md,再给一段合并去重 prompt(run: false 只出 prompt) |
expert_workspace |
在专家目录下开独立工作区,直接建好会话、投递开场提示;这一轮结束时把 workspace\out\*.md 收成一条进度记录 |
expert_status |
读当前状态:目标、步骤完成度、最近记录 |
expert_mode |
只切模式,不动步骤与进度 |
expert_next |
串行模式取下一步,附现成的子任务提示;expert_record 会拦住跳步(确要跳传 force 并写原因) |
expert_find |
按问题在专家库里找资料;找不到返回 missing: true,提醒先问用户 |
expert_ingest |
把手头一份资料(目录或文件)搬进专家库:只给路径即可,标题/主题/一句话会推断并标「自动推断」 |
lookup_expert_knowledge |
按问题关键词查「该先读哪几份」,返回中文名、路径、所属技能;查不到返回 missing 并提醒先问用户 |
星级怎么算
五颗星,前四颗只看资料本身,第五颗才看有没有被用过。
| 星级 | 名字 | 意思 |
|---|---|---|
| ★☆☆☆☆ | 起步 | 资料还薄,或者索引/说明没补齐 |
| ★★☆☆☆ | 可用 | 结构完整、覆盖够用,能拿来查了 |
| ★★★☆☆ | 可靠 | 主题分得匀、内容写得实,多数问题能查清 |
| ★★★★☆ | 权威 | 结构、覆盖、内容、新鲜度都到位,调研计划做完了 |
| ★★★★★ | 标杆 | 已经到权威,而且真的被用过(使用分 ≥ 50、至少 2 个会话) |
内容分由五个维度加权得出:
| 维度 | 权重 | 看什么 |
|---|---|---|
| 结构完整度 | 0.25 | 文件在盘、进索引、索引有说明、中文名、桌面快捷方式,五项各占一部分 |
| 覆盖均衡 | 0.25 | 资料总量、主题分布是否均衡、平均每主题几份 |
| 内容可用度 | 0.20 | 文件是否够大、有没有来源链接、有没有写结论 |
| 新鲜度 | 0.15 | 按半衰期折算:生图 90 天,游戏/阅读器/插件 180 天,界面/短剧/播放器 365 天;若在 manifest.json 的 reviews 里写了复核日期,就按复核日期算 |
| 调研闭环 | 0.15 | 计划完成率、记录里有没有带数字的结论 |
使用分只影响最后一颗星:被几个会话用过、读到多深、读后有没有产出;占位加载不算。
面板里每位专家都有一栏「为什么是这个星级」:逐条写「资料齐不齐 / 主题分得匀不匀 / 写得实不实 / 新旧程度 / 调研做到哪一步 / 有没有人用过」,再写「离下一颗星还差什么」。
两个可选的小文件,能让它更准
references/queries.md:写 8–12 条「用户会怎么问 → 该命中哪份 → 要点」,插件会自己跑一遍,告诉你「10 个常见问题里有几个能直接找到」。没有这个文件就不算这项,不扣分也不编造。manifest.json的reviews:形如{"references/prompt-basics": {"reviewedAt": "2026-11-16"}},记录某份资料哪天复核过;不写就按文件修改时间算新旧。
一份资料只有一个家
一份资料只写进一个专家的 manifest.json 的 topics[].files;别处要用,只写一行指针(带触发条件),文件本体不复制。
判断标准:把结论换到「某个 App」上仍然成立,就该归通用的 ui-design;必须靠这个产品的专有名词才说得清,归产品专家。
登记完跑一遍检查:
node scripts/check-ownership.mjs "<你的专家库根目录>"
它遍历每个 manifest.json,同一路径出现两次就报错(退出码 1)。
调用方式与调研方式
面板右上角齿轮进设置页,两组选择都写进库根 settings.json,改完立即生效。
调用方式(mode 字段):
| 档位 | mode |
行为 |
|---|---|---|
| 自动识别 | auto |
这句像某位专家的领域就在回合开头提醒一次;查过就不再提醒 |
| 点名才查 | on-request |
默认。只有你说「调用 / 问问 / 请教 / 查阅某专家或某资料库」时才提醒;其余输入完全不碰 |
| 不主动调用 | off |
任何输入都不提醒、系统提示里也不出现这条规则;专家库只是个静态资料库,expert_create/plan/dispatch/ingest 这些建库工具照常可用 |
调研方式(research 字段):
| 方式 | research |
行为 |
|---|---|---|
| 并行 | parallel |
expert_dispatch 给每个未完成步骤各开一个子会话同时查,结果自动回写,再给一段合并去重 prompt |
| 串行 | serial |
默认。用 expert_next 取下一步,查完 expert_record 记结论再取下一步;expert_record 会拦住跳步(确要跳传 force 并写原因) |
| 独立工作区 | workspace |
在专家目录下另开会话跑,不占主对话上下文;子会话继承你当前会话的预设,读写工具都在 |
也可以直接改文件:
{ "mode": "on-request", "research": "serial" }
插件自己开的派发子会话与工作区会话只用来造资料:它们会并进发起它们的那个会话里显示,但不算「用过的专家」,也不进使用统计。
配置
| 变量 | 默认 | 说明 |
|---|---|---|
DSH_EXPERT_ROOT |
插件内置默认目录 | 专家库根目录:每位专家一个子目录,资料放进该专家的 references/ |
它是怎么工作的
- 宿主侧通过
ctx.skills.registerProvider()把专家库接进技能系统:list()只返回名称和简介,get()才读SKILL.md正文,所以没被点名的专家不占上下文。 ctx.tools.register()注册上表 12 个工具,写盘后让技能缓存失效,新专家立刻可见。- 监听
agent/pre-step:按settings.json的mode决定——auto用主题词命中、on-request只认「调用 / 问问 / 查阅 + 专家或资料库」的明确指令、off直接返回。命中后在本步消息末尾插一行「先查资料库」,同一回合只提醒一次,查过的回合不再提醒。不再用agent/turn-stopping硬拽模型。 ctx.systemPrompt.section()注入的规则文本跟着mode走:auto允许自己判断,on-request写明「用户没点名就别查」,off返回空字符串(等于不注入)。- 监听
tools/post-execute:加载专家技能、读专家目录里的文件、派子智能体,都写进 trace,并在下一轮回复里插一行徽标。 - 面板和 trace 通过 5 个只允许本机访问的 HTTP 路由读取,路径校验拒绝越界访问。
面板里能看到什么
左栏「专家库」三个页签:
- 概况:一句话总结(「最近 30 天,模型读了 33 次资料」)、4 个关键数字、30 天读取柱状、8 周×7 天活跃热力、五位专家的阶段分布、读得最多的 5 份资料、最近 5 件事。
- 资料:每位专家一张卡片(星级、主题数、资料数、上次被用),点开按主题列出「你要做什么 → 该读哪几份」,再下面是全部文件与技能说明。
- 调用记录:按会话分块,每块写「用到的专家:AI 生图 ×3、界面与交互 ×1」;顶部下拉可只看某个会话或「本机脚本写入」;子会话不单列,行内第二行标「子会话 · 派发任务名」。
常见问题
装完为什么没出现「专家库」? 安装改了 bundle 组合,必须重启一次 DSH。之后改插件代码不用重启——宿主侧走 hmr 热替换,浏览器侧刷新页面即可。
为什么我新建的会话在调用记录里只显示「未命名会话」? 面板按 5 秒轮询读会话文件;新会话的标题还没落盘时先显示占位,刷新后会换过来。
星级升不上去怎么办? 打开该专家卡片看「为什么是这个星级」,逐维写了差什么:「资料齐不齐」「主题匀不匀」「写得实不实」「新旧程度」「调研做到哪一步」「有没有人用过」,以及离下一档差多少。
测试
node --test test/*.test.js # 单元测试
node scripts/host-smoke.mjs # 假 ctx 跑一遍宿主侧注册
node scripts/client-smoke.mjs # 假模块加载器跑一遍浏览器侧注册
局限
- 模型会不会主动加载专家,取决于
description、when-to-use和注入的规则;写得太泛仍可能被通用技能抢走。 - 成熟度里的「真实使用」只看本机 trace;换机器或清空
.trace后会重新从 0 累积。 - 面板轮询 5 秒一次,不推送;调用记录要刷新才更新。
- 只监听
DSH_EXPERT_ROOT下的目录,不做向量检索。
No comments yet. Be the first to write one.