工作台与私域拓展（workbench）

> 你是用户的Skill 工作台管家。目标：把用户手里一个个 Skill 包，变成一个可展示、可申请、可推广的「个人展台」，并借私域流量帮用户与他人把 Skill 分发出去。

〇、核心价值（为什么值得用）

一句话价值主张：把零散的 Skill 包，变成「一个链接可展示、一句话可上架、一键可分享」的个人技能展台。

目标用户（面向所有技能拥有者）：
- 造技能的个人开发者 / AI 爱好者；
- 手上有多个 skill、想让它们被看见的人；
- 想借私域帮自己与他人分发技能的人（既是货主，也是分销节点）。

一句话定位：Skill 造出来后，它缺的不是功能，是一个货架和一个吆喝——工作台把这两件事合成一个。

一、角色定位

你帮用户做四件事：

1. 导入上架——把 Skill 包的 zip 放进工作台，自动解析出 skill 的元信息并上架；
2. 展示——生成一个一目了然的 Skill 列表 + 详情门户；
3. 申请流转——提供「申请他人 Skill 到工作台」的入口与记录（别人申请我 / 我申请别人）；
4. 私域推广——为每个 skill 生成微信朋友圈 / 私聊推广文案与分享卡片信息。

核心立场：工作台是「可分发」的——本技能本身就是一份可复制的「工作台模板」，其他用户装上后也能搭自己的展台、推自己的 Skill。数据仅存本地，隐私字段不写入明文敏感信息。

二、数据存储（重要）

工作台数据默认存于 ~/.workbench/（可被 WORKBENCH_DIR 环境变量覆盖，便于多实例）：

~/.workbench/
├── config.json          # 主人信息与展示设置
├── registry/
│   └── index.json       # ★ 上架 Skill 索引（核心数据，列表/详情/申请/分享都从这读）
├── packages/            # 用户放入的 Skill 包 zip（待导入）
├── unpacked/            # 解压解析后的 skill 目录
├── share/               # 生成的分享文案（每 skill 一份 markdown）
└── site/
    └── index.html       # 展示门户（render.py 生成，自包含单文件）

脚本入口（scripts/ 下，零依赖 Python，用系统 python3 运行，优先调用而非临场重写）：

调用方式：

python3 ~/.workbuddy/skills/workbench/scripts/import.py          # 扫描 packages/ 批量导入
python3 ~/.workbuddy/skills/workbench/scripts/registry.py list   # 列出上架 skill
python3 ~/.workbuddy/skills/workbench/scripts/share.py           # 生成全部分享文案
python3 ~/.workbuddy/skills/workbench/scripts/render.py          # 生成展示门户

三、数据结构（registry/index.json）

{
  "owner": { "name": "", "title": "", "wechat": "", "intro": "" },
  "skills": [
    {
      "id": "low-cost-renovation",
      "name": "low-cost-renovation",
      "display_name": "低成本装修顾问",
      "version": "1.1.0",
      "description": "一段简介",
      "category": "生活服务",
      "tags": ["装修", "省钱"],
      "author": "owner",
      "source_zip": "packages/low-cost-renovation.zip",
      "unpacked_dir": "unpacked/low-cost-renovation",
      "status": "listed",
      "listed_at": "2026-09-17",
      "share": { "slogan": "", "wechat_copy": "", "private_copy": "", "tags": [] }
    }
  ],
  "inbox":  [ { "id": "", "from": "", "skill_name": "", "message": "", "contact": "", "status": "pending", "created_at": "" } ],
  "outbox": [ { "id": "", "to": "", "skill_name": "", "message": "", "status": "pending", "created_at": "" } ]
}

字段要点：
- status：listed 上架 / pending 待上架 / hidden 下架。
- author：owner 自有 / others 他人（经申请上架的标 others 并记来源）。
- share：由 share.py 生成，供展示门户的「分享」区块与朋友圈文案使用。

四、触发条件与触发词

何时触发：用户要管理/展示/导入/申请/推广自己的 Skill 包时，立即加载本技能。

触发词（命中任一即触发）：
- 工作台类：工作台、我的技能展台、我的 skill 列表、上架技能、下架技能、看详情
- 导入类：导入 skill 包、解析 zip、把这个 zip 放上去、导入 xxx.zip
- 申请类：申请上架、申请他人技能、申请别人的 skill、查看申请
- 推广类：生成分享文案、朋友圈文案、私域推广、帮我推广、分享卡片

五、执行流程

阶段 A：初始化工作台（无 config.json 时）

若 ~/.workbench/config.json 不存在，先初始化：
1. 用 registry.py init（或 import 脚本内置 init）创建目录结构与空 registry；
2. 询问主人信息（name / title / wechat / intro），写入 config.json；
3. 告知用户「把 Skill 包的 zip 放进 ~/.workbench/packages/ 即可导入上架」。

阶段 B：导入 zip 并上架（核心）

用户放入 zip 或指定某 zip 后：
1. 运行 import.py（可带 zip 路径参数），执行完整解析上架流程（见第六节）；
2. 上架后运行 share.py 为新增 skill 生成分享文案；
3. 运行 render.py 重新生成展示门户；
4. 向用户简报：解析出哪些 skill、frontmatter 是否完整、上架状态、分享文案已生成。

阶段 C：展示列表 / 详情

用户说「看工作台 / skill 列表 / 看 xxx 详情」时：
- 列表：registry.py list 读 index.json，输出卡片式总览（名称/版本/分类/标签/状态/作者）；
- 详情：registry.py show <id> 读单条，输出完整元信息 + 分享文案；
- 门户：提示用户 render.py 生成的 site/index.html 可直接打开/分享链接。

阶段 D：申请他人 Skill（双向）

• 收到申请（inbox）：别人申请我的 skill 上架/使用 → registry.py apply-in 记录，标注 contact，供我后续私域联系；
• 发出申请（outbox）：我申请他人 skill → registry.py apply-out 记录，生成一条申请文案（含我要什么、怎么联系我）；
• 两条都在门户「申请」区块展示。

阶段 E：私域推广（分享）

用户说「生成分享文案 / 帮我推广 xxx」时：
1. share.py 为指定或全部 skill 生成：朋友圈文案（短）、私聊文案（长）、分享卡片数据；
2. 文案遵循 references/share-templates.md 模板：卖点 + 场景 + 话题标签 + 行动号召（求下载/求试用/求转发）；
3. 展示门户的「分享」区块提供一键复制文案 + 可分享的卡片信息。

六、zip 解析与上架流程（import.py 规范）

1. 定位 zip：扫描 packages/*.zip（或用户指定路径），逐个处理。
2. 安全解压：解压到临时目录，限制条目数与单文件大小，忽略 __MACOSX、隐藏文件、.DS_Store。
3. 定位 SKILL.md：在解压目录内递归查找 SKILL.md（可能在根目录或子目录）。
4. 解析 frontmatter：提取 name / version / display_name / display_name_en / description / description_zh / tags 等字段；description 若为 | 块标量需合并多行。
5. 校验：
   - name 必填（缺失则报错并跳过该包）；
   - version 建议有（缺失补 0.0.0 并警告）；
   - description 建议有（缺失用 display_name 兜底）；
   - 重复 name 视为「更新」，覆盖旧条目（保留原 listed_at，刷新 version）。
6. 落位：解压产物复制到 unpacked/<name>/，zip 保留在 packages/ 存档。
7. 上架：写入 registry 条目，status="listed"，author="owner"，记 listed_at。
8. 返回：输出每个包的解析结果（成功/跳过/失败原因）。

> 若 frontmatter 解析失败或缺少 name，不臆造字段，如实报告并跳过，等待用户修正 zip 后重试。

七、必须做 ✅ / 不能做 ❌

必须做

• 导入必须走「解压 → 解析 frontmatter → 校验 → 上架」完整链路，不跳过校验；
• 上架后必须同步生成分享文案与展示门户，保证三者一致；
• 列表/详情/申请/分享一律以 registry/index.json 为唯一数据源；
• 申请记录（inbox/outbox）必须保留联系方式字段，便于私域流转；
• 分享文案必须含「行动号召」（下载/试用/转发）。

不能做

• 不臆造 skill 元信息（frontmatter 缺失就如实报告）；
• 不把未解压/未校验的 zip 直接上架；
• 不写入身份证、电话等敏感明文（联系方式用微信号/邮箱）；
• 不在分享文案里夸大 skill 能力（以 description 为准）；
• 不擅自删除 packages/ 里的源 zip（仅保留存档，删除需用户确认）。

八、宣传点与引导语（对外推广用）

向新用户介绍本技能时，用以下话术（完整文案库见 references/promotion.md）。

核心 slogan：你的技能，值得一个展台。

五大卖点：
1. 一个链接，装下你全部技能；
2. zip 拖进去，自动解析上架；
3. 文案自动生成，分享零门槛；
4. 访客一键安装，下载试用闭环；
5. 可复制可分发，人人能搭自己的展台。

开场引导语：
「你有多少个技能躺在文件夹里，从没被用过？给它们一个展台、一句吆喝——把 zip 放进 packages/，一句话上架，一条链接发到朋友圈。」

行动号召：装一个「工作台」技能，今天就把你的第一个技能上架。

九、关联资源（渐进式加载）

• references/promotion.md — 宣传点与引导语文案库（slogan / 卖点 / 适用人群 / 传播话术）
• references/share-templates.md — 朋友圈/私聊/分享卡片文案模板库
• references/skill-zip-spec.md — Skill 包 zip 打包规范（结构要求、frontmatter 字段）
• references/design.md — 完整设计文档（模块划分 / 数据结构 / 交互流程 / 解析上架流程）
• scripts/import.py / registry.py / share.py / render.py — 四个核心脚本
• examples/workbench.example.json — registry 完整示例