专家包零积分生产流程
内置 expert-manager 技能是规范来源，先加载它读全文。本技能只补充它没写清、且实际会踩坑的部分。
为什么要有这个技能
expert-manager 的流程里写「参考 avatar-spec.md 使用 ImageGen 生成头像」。头像生成属于 AI 生图，计费。本技能记录的是跳过这一步也能交付的实证——不要一上来就烧积分。
关键实证（已在本机验证）
| 事实 | 影响 |
|---|---|
avatars/ 里只要有 .gitkeep，plugin.json 里的 avatar 指向不存在的文件只会报警告级别的检查被静默跳过，校验输出为全绿 |
头像非必需，可零积分交付 |
| 用户已有的 3 个专家包头像目录全是空的，仍注册成功 | 佐证同上 |
.gitkeep 由 init_expert.py 自动创建 |
不要手动删它，删了就会触发头像缺失警告 |
结论：默认走零积分路线——先把包做完整并注册，头像单独作为可选项向用户报价（Agent 型 = 1 张，Team 型 = N+1 张），拿到明确同意再调 ImageGen。
真实路径（勿猜）
- 专家目录：
$WORKBUDDY_CONFIG_DIR/plugins/marketplaces/my-experts/plugins（本机WORKBUDDY_CONFIG_DIR=C:\Users\QING\.workbuddy） - 元数据目录名是
.codebuddy-plugin（不是.workbuddy-plugin）。init_expert.py写的是前者，register_expert.py两者都认，但新包统一用.codebuddy-plugin - 市场索引：
<my-experts>/.codebuddy-plugin/marketplace.json，由register_expert.py自动写入，禁止手改 - 包内布局：
agents/、skills/、avatars/、bin/必须在包根，放进.codebuddy-plugin/里会直接报错
硬红线（校验器会拦或会告警）
displayDescription.zh必须 40–50 字（超了只是 warning，但展示会难看）。tags恰好 3 个，quickPrompts恰好 3 个，且defaultInitPrompt必须等于quickPrompts[0]。- Agent MD 的 frontmatter 不得出现
tools字段。 - frontmatter 的
name必须等于 MD 文件名（不含.md）。 plugin字段必须等于name。categoryId必须取自那 12 个合法值之一。name必须 kebab-case，且包目录名 =name。- 不允许出现
hooks/、commands/、.lsp.json。
字数必须用脚本数
手工数字数两个方向都会错。每次改完 displayDescription.zh 都要跑一次：
python -c "s=open('.../plugin.json',encoding='utf-8').read(); import json; print(len(json.loads(s)['displayDescription']['zh']))"
多候选版本一次性比对（省往返）：
python -c "
c=['候选1','候选2','候选3']
for i,s in enumerate(c): print(i,len(s),'OK' if 40<=len(s)<=50 else 'OUT',s)
"
裁剪策略：先删「多模态」「配送」这类修饰词，保住专有卖点词（如「自动驾驶」「质检阈值」）。
categoryId 判定顺序
- 主要输出物属于哪个领域
- 服务对象是谁
- 跨领域时取最核心的一个，并向用户说明理由
工程类角色（诊断、结构、算法、仿真）→ 02-Engineering；数据/模型/标注 → 04-DataAI；泛行业说不清的 → 12-IndustryConsultant。
expertType 判定
- 原始资料是单一人设 →
agent - 资料里明确有多个角色的分工与 SOP →
team - 单角色但覆盖多领域，仍是
agent（多能力不构成 team）。想升级成 team 是产品策略问题，不是技术判定问题，要单独跟用户确认。
标准执行顺序
1. 侦察：读 WORKBUDDY_CONFIG_DIR、列已有专家、读一个已有专家的 plugin.json + MD 学风格
2. init_expert.py <name> --type agent|team --path <专家目录> # --path 必须是专家目录，否则脚本直接拒绝
3. 覆写 plugin.json / agents/*.md / README.md（Write 前必须先 Read，否则工具拒绝）
4. 需要参考资料时加 skills/<skill-name>/SKILL.md + references/*.md，并在 plugin.json 的 skills 数组声明
5. 脚本核 displayDescription 字数 + 扫 [TODO] 残留
6. validate_expert.py → 必须全绿
7. register_expert.py → 这一步才让它出现在「我的专家」
8. package_expert.py <expert-dir> <output-dir> 产出可分发 zip
9. 报价头像（可选、计费），拿到同意再动
踩坑记录
- Write 工具要求先 Read：
init_expert.py生成的模板文件必须先Read一次再Write，否则报 "File has not been read yet"。 - 不要用
&&串长命令：本机 Bash 沙箱对复合命令（含变量赋值 +&&）可能直接报decisionRecord missing actual resource subject。拆成单条、用绝对路径调用解释器最稳。 --path传错目录会被脚本硬拒，提示「非专家目录下创建的专家无法被检测到」。- 用户已有专家包是学风格的最佳样本：看他现有专家的第一人称人设口吻、是否给角色起中文名、输出规范写得多细，比从零设计更贴合他的审美。
