小浣熊专家生成器
> <META_DIR> 是平台元数据目录名，由宿主平台定义，实际取值见
> schemas/platform-contract.json 的 metaDir.primary。本文用占位符而非
> 字面量，换平台时只需改契约那一个字段。
零、不可突破的红线
- 不改唯一标识。
plugin.json的name、agentName、专家目录名、agents/*.md文件名构成唯一标识，修改会导致专家失联。用户要求改名时，说明「改名需重建专家」，不原地改。 - 不生成到专家目录之外。专家目录由运行时配置决定（见第三章）。其他目录生成的包无法被检测到，即使用户明确要求也不例外。
- 不在 frontmatter 声明 tools。工具权限由平台统一分配，写了会被校验拦下。用户要求「加 tools 让它能调 X」时，引导改用附属 Skill 承载能力。
- 不编造信息。作者、授权、引用来源、成员职责等无法从材料推断的字段，标记为待确认并回问，禁止凭空填写。
- 不手写 marketplace.json。该文件只能由注册脚本写入，手写会绕过完整性校验并导致静默失败。
- 不把密钥类文件放进包。
.env、*.pem、*.key、*.p12、硬编码 Token 一律排除，打包阶段强制过滤。 - 不跳过校验直接注册。即使目标目录已存在、看似「已经生成过」，也要走完整的校验与注册流程。
- 不替用户拍板展示文案。能力描述、3 条推荐提示词、行业分类由 AI 起草，用户确认后才落盘。
一、核心能力速查
| 功能 | 说明 | 触发关键词 |
|---|---|---|
| 形态判断 | 判定该做单技能包、单角色专家、专家团，还是不成包 | 该做成什么形态、要不要多角色 |
| 专家包初始化 | 生成带占位符的完整目录骨架 | 创建专家、初始化专家包 |
| plugin.json 生成 | 双语展示字段、分类、标签、提示词 | 生成 plugin.json |
| 提示词生成 | Agent 与主理人的正文结构与协作铁律 | 写专家提示词、生成 agent md |
| 资料转化 | 把现成资料映射为专家包结构 | 转化这份资料、做成专家 |
| 头像生成 | 按角色特征与分类色调生成头像 | 生成专家头像 |
| 合规校验 | 字段、结构、命名、密钥四类检查 | 检查专家包、合规检查 |
| 质量评分 | 五维打分，85 分且无阻断项才可交付 | 打个分、质量评估 |
| 注册 | 写入 marketplace.json 使其在中心可见；内容未变则跳过重写 | 注册专家、上架专家 |
| 打包 | 校验通过后归档，文件名自动带版本号 | 打包专家、导出 zip |
| 环境体检 | 打印专家目录的实际位置 | 专家目录在哪、包该放哪 |
| 阶段判定 | 判定包处于八阶段中的哪一态并给出证据 | 我这包到哪一步了 |
| 缺口清单 | 列出还差什么，每项带可粘贴的命令 | 还差什么、怎么补 |
| 批量体检 | 跨全部包汇总阶段分布 | 哪些包没做完 |
| 错误码反查 | 查某码的文件、字段与验证命令 | XX 码什么意思 |
| 行为层门禁 | 查角色定位、边界声明、输出契约 | 提示词答非所问检查 |
| 领域蓝本 | 6 份素材型蓝本（术语、问法、失败模式） | 这个行业怎么写提示词 |
二、标准工作流
前置：确认运行环境
先确认专家目录位置，不要靠报错反推：
python3 scripts/doctor.py env
脚本按运行时配置变量解析，未设置时回落到用户主目录下的默认路径。若用户要求生成到其他路径，直接说明「专家必须生成到专家目录才能被检测到，其他目录生成后将无法使用」，并把上一步打印的目录原样给用户。
步骤 1：收集信息
必须收集：核心能力领域、专家类型、中文花名、职业头衔、能力描述（40-50 字）、行业分类、3 个标签、3 条推荐提示词、首次问候语。Team 型另需：团队名称、成员名单与分工。
判定专家类型的唯一标准：有没有用户会直接问它的问题。每个能力域都能被独立提问用 Agent 型；多个能力域需交叉验证或冲突消解用 Team 型。
步骤 2：形态判断（可选）
不确定该交付什么形态时，先跑判断：
python3 scripts/decide_form.py examples/input-requirement.md
四种结论：不做包（一次性任务）、单技能包、单角色专家、专家团。用户说「就这一次」且无重复路径时，明确告知不建议成包。判断依据见 references/workflow.md。
步骤 3：初始化目录
python3 scripts/init_expert.py <expert-name> --type agent|team --path <expert-plugins-dir>
生成 <META_DIR>/plugin.json、agents/*.md、avatars/、README.md，Team 型另生成 settings.json 与团员占位 MD。所有字段带占位符。
步骤 4：填充内容
按依赖顺序填，避免前后不一致：
- 先定身份：
name、目录名、agentName、MD 文件名。四者一致，且一经确定不再改动。 - 再填展示：
displayName、profession、displayDescription、tags、quickPrompts、defaultInitPrompt。注意后两者必须逐字相同。 - 再定分类：
categoryId，按判定优先级选择并向用户说明理由，见references/category-id-map.md。 - 最后写正文：核心能力、工作流程、输出规范、注意事项。Team 型主理人须含协作铁律与严禁行为段。
- 派生字段由身份反推：
plugin、agents数组、teamInfo、members。
填完确认无残留：
grep -rn "\[TODO" <expert-dir>
步骤 5：生成头像
按 references/avatar-spec.md 执行。三个要点：prompt 必须从该角色的 MD 提取，不用通用模板；同一专家团共用风格锚定词；背景色调跟随 categoryId。Team 型是 N+1 张，别漏主理人。
生成失败不阻断流程，在 README 标注待补并附推荐 prompt。
步骤 6：校验
python3 scripts/validate_expert.py <expert-dir>
校验不通过时逐条修，不绕过。想知道某个码改哪里：
python3 scripts/validate_expert.py --explain <CODE>
会打印该码的文件、字段与一条可直接粘贴的验证命令。码表由 schemas/error-codes.json 生成，改码表请改 JSON 后跑 python3 scripts/validate_skill.py --sync-codes。
不知道还差什么时，用缺口清单代替逐条读报错：
python3 scripts/doctor.py gap <expert-dir>
每项按错误码分组、带可执行命令，同一个码出现 21 次只显示一行。
校验通过不等于提示词可用。 结构合规但答非所问的包，校验器看不出来（这是它的职责边界，见 references/scripting-boundary.md）。交付前加跑行为层门禁：
python3 scripts/qa_gate.py <expert-dir>
三项强制检查：角色定位一致性、边界声明、输出契约。证据落在 <expert-dir>/.qa/round-N.json。
可选：跑质量评分拿到五维报告。
python3 scripts/score_expert.py <expert-dir>
总分 85 以上且无阻断项才建议交付。
步骤 7：注册
python3 scripts/register_expert.py <expert-dir>
脚本二次校验关键字段无占位符后写入 marketplace.json，并注入会话标识。修改已有专家后同样要重跑这一步，否则改动不生效。
注册是幂等的：内容指纹未变则输出 action: skipped，不动清单文件。只改了展示字段（displayDescription 等）时属这种情况。需要强制重写加 --force。判定表见 references/modify-existing.md。
注册后确认 .raccoon-state.json 已生成——指纹存在里面，没有它下次会白写一次清单。
步骤 8：打包
python3 scripts/package_expert.py <expert-dir> [output-dir]
打包前自动跑一次校验，不通过则中止。产物为 <expert-name>-v<MAJOR>.<MINOR>.<PATCH>.zip，版本号从 plugin.json 自动读取，不手写。
三、任务状态机
| 状态 | 含义 | 下一步动作 |
|---|---|---|
collected |
信息已收齐，形态待定 | 跑形态判断或直接定类型 |
scaffolded |
目录骨架已生成，字段仍是占位符 | 填充内容 |
filled |
占位符清零，展示字段已定 | 生成头像 |
illustrated |
头像齐备或已标注待补 | 校验 |
validated |
校验通过 | 注册 |
registered |
已写入 manifest，中心可见 | 打包 |
packaged |
ZIP 产物已生成 | 交付 |
blocked |
校验或注册被拒 | 按错误码逐条修复后回到上一状态 |
恢复规则：任何阶段中断后，不要凭记忆假设状态，让脚本判定：
python3 scripts/doctor.py status <expert-dir>
它给出八阶段中的具体一态加判定证据（如「plugin.json missing: displayName, profession」），证据比状态名更有用。批量看所有包用 doctor.py all。
已存在同名目录时：不要重新初始化。先跑 doctor.py status 判断状态，需要更新就重跑注册。改动已有包的完整流程与不可回退项见 references/modify-existing.md。
四、数据合规与安全
- 密钥类文件（
.env、*.pem、*.key、*.p12、id_rsa、credentials）一律不进包，打包阶段强制排除。 - 硬编码 Token、API Key、Bearer Token 在校验阶段报错并定位到文件与行号。
- 专家包内容全部落在本地文件系统，不做外发；上传 ZIP 属外发动作，执行前须用户确认。
- 引用第三方资料时保留来源，不把他人受版权保护的正文整段搬入包内。
- 生成内容涉及违法、侵权、隐私泄露或不合规用途时直接拒绝。
- 涉及外部系统、账号授权、文件删除的动作，执行前明示风险。
五、性能与容量
| 操作 | 典型耗时 | 基线规模 | 说明 |
|---|---|---|---|
| 形态判断 | < 0.1 秒 | 十万字以内需求文档 | 纯文本扫描 |
| 初始化 | < 0.2 秒 | — | 写 4-6 个文件 |
| 校验 | < 0.5 秒 | 50 个文件以内 | 递归扫描 + 密钥正则 |
| 质量评分 | < 0.8 秒 | 10 个 Agent 以内 | 逐 MD 解析 |
| 注册 | < 0.3 秒 | 200 条 manifest 以内 | 读改写 JSON |
| 打包 | < 1 秒 | 20MB 以内 | 校验后归档 |
规模上限参考：单专家团成员建议不超过 8 个（校验在 8 个时告警），超过 8 个应先考虑合并分析域。头像生成是外部调用，1 张约 3-8 秒，Team 型 N+1 张串行执行。
六、交付形态
| 产物 | 路径 | 命名 |
|---|---|---|
| 专家包目录 | 专家目录下 | <expert-name>/ |
| 注册清单 | 专家目录下 | marketplace.json（脚本写入） |
| 质量报告 | 专家包内 | quality-score-report.md |
| 打包报告 | 专家包内 | package-report.json |
| 分享产物 | 指定输出目录 | <expert-name>-v<MAJOR>.<MINOR>.<PATCH>.zip |
交付标识：每个产物在正文首行标注生成方式与版本，便于溯源。
版本一致性：plugin.json 的 version、ZIP 文件名版本必须一致，不一致则阻断打包。版本号一律从 plugin.json 读取，不手写。
收尾必告知用户四件事：头像可否替换及其规格、注册状态与查看路径、打包命令与产物路径、请用户核对展示字段与分类是否准确。
七、交付前自检
| 维度 | 检查项 | 通过标准 |
|---|---|---|
| 字段 | 双语完整、数量锁定、问候语对齐、Team 型 profession 一致 | validate_expert.py 零错误 |
| 命名 | 四处标识一致、成员花名不与职业重复、主理人文件名带前缀 | 无 NME 类错误或告警 |
| 提示词 | 章节完整、无残留占位符、Team 型含铁律与回传要求 | score_expert.py 的 Prompt 维度满分 |
| 合规 | 分类合法、无禁止目录、密钥扫描通过 | 无 SEC 与 PKG007-009 错误 |
| 交付 | 头像齐备、README 存在、版本一致 | 总分 ≥ 85 且无阻断项 |
任一维度不达标即不交付。工具不能替代人工确认分类归属与文案质量。
八、何时不用本技能
| 场景 | 原因 | 改用 |
|---|---|---|
| 一次性提示词 | 不需要形成可安装包 | 直接对话生成 |
| 纯文档写作、数据分析、代码开发 | 与专家包无关 | 对应领域工具 |
| 修改既有 SkillHub 技能包 | 产物结构不同 | 技能包创建流程 |
| 需要直连平台 API 完成注册 | 本技能只写本地 manifest | 平台开放接口 |
| 涉及违法、侵权、隐私泄露 | 红线 | 无，拒绝执行 |
| 打包上传到外部平台并发布 | 发布属人工审核动作 | 人工上传 |
九、常见问题
Q：为什么生成的包在专家中心看不到？
A：九成是没注册。目录生成后必须跑 register_expert.py，只生成不注册不会出现在中心。另外确认包在正确的专家目录下。
Q：能不能改专家名字？
A：不能原地改。name、agentName、目录名、MD 文件名都是唯一标识，改了会失联。需要改名只能重建，然后手动迁移内容。
Q：tags 已经有 3 个了，还能加吗？
A：不能。标签固定 3 个，已满时只能替换或删除其中一项。
Q：agentName 写了 team-lead 为什么报错？
A：通用名会与其他专家团路由冲突。主理人文件名必须带专家团前缀，如 trading-team-lead.md。
Q：Team 型 profession 该怎么填？
A：Team 型的 profession 必须与 displayName 完全相同。但主理人 Agent MD 里的 profession 不能用「团长」「主理人」这类通用 title，要用「交付总监」「首席策略官」这类体现调度风格的头衔。
Q：Agent 型和 Team 型怎么选？
A：按「有没有用户会直接问它的问题」。能力域能独立提问用 Agent 型；多个域需交叉验证、冲突消解用 Team 型。拿不准先做 Agent 型，成员超过 4 个再升级。
Q：分类该选哪个？
A：按优先级判定：主要输出物属于哪个领域，其次服务对象是谁，跨领域选最核心的。详见 references/category-id-map.md。
Q：头像生成失败了怎么办？
A：不阻断流程。在 README 标注哪张待补，附上按角色特征写好的 prompt，等用户自行补。Agent 型 1 张，Team 型 N+1 张。
Q：提示词里能声明 tools 吗？
A：不能。权限由平台统一分配，frontmatter 声明会报错。需要额外能力就挂附属 Skill。
Q：能打包多个专家一次上传吗？
A：可以逐个打包。每个包单独校验注册，产物各自带版本号。不要为了省事批量手写 manifest。
Q：校验脚本报密钥错误，但代码里只是常量？
A：正则可能误判示例代码里的假 Token。改写变量名避免连续 16 位以上字母数字组合，或移到 references 文档里说明。
十、参考文件
按需读取，不必全部加载：
| 文件 | 何时读 |
|---|---|
references/workflow.md |
需要七阶段细节、状态恢复、修改已有专家流程时 |
references/plugin-json-spec.md |
填字段、对齐展示信息、排查校验错误时 |
references/agent-md-spec.md |
写 Agent 或主理人提示词、拆分析域时 |
references/team-spec.md |
建专家团、定成员命名、编排 SOP 时 |
references/category-id-map.md |
选行业分类、生成头像定色调时 |
references/avatar-spec.md |
生成头像、写 prompt 时 |
references/material-conversion.md |
用户提供现成资料需要转化时 |
references/naming-conventions.md |
定名字、对齐标识、打包版本时 |
references/error-codes.md |
校验报错需要定位修法时（由 schemas/error-codes.json 生成，勿手改） |
references/modify-existing.md |
改已注册的包、判断要不要重跑注册时 |
references/scripting-boundary.md |
判断某个检查该不该交给脚本时 |
references/permissions-guide.md |
涉及权限、注册边界、人工审核红线时 |
source-map.md |
想知道这个包怎么来的、吸收了什么、哪些 PRD 项没落地时 |
blueprints/ |
写某个行业的提示词前取素材（术语、问法、失败模式） |
templates/ |
需要可复制的模板骨架时 |
examples/ |
需要参考完整实例时 |
