Skill Studio 操作说明书

1. 登录与角色

1. 1

   在浏览器打开 Skill Studio 地址（默认开发环境为 http://localhost:3105）。

   • ·未登录会自动跳转登录页。
2. 2

   输入用户名、密码与图形验证码登录。

   • ·账号由管理员在「用户管理」中创建，角色需为管理员或 Skill 开发者。
3. 3

   登录后进入会话工作台。

   • ·观察者角色无法登录 Studio。

2. 界面总览

Studio 采用「会话式布局」：左侧会话列表，右侧为「对话 / 文件 / 测试」三个页签。

• 会话侧栏：一个会话对应一个 Skill 开发过程，含草稿与已建 Skill 的徽章。
• 对话页签：与 AI 对话，生成或修改 Skill 文件。
• 文件页签：文件树 + Monaco 编辑器，查看与保存文件。
• 测试页签：从 manifest 生成参数与环境变量表单，调用执行面运行技能。
• 底部入口：查看 Admin 菜单（分类与卡片，只读）。

3. 配置 LLM 与 Admin 地址

Studio 使用独立的 LLM 配置驱动「Skill 创建助手」，也可配置 Admin 地址用于查看菜单与发布联动。

1. 1

   点击设置入口，打开设置弹窗。

   • ·设置保存在 ~/.studio/settings.json，换进程不丢失。
2. 2

   填写 LLM 的 Base URL、API Key 与 Model ID。

   • ·建议使用 OpenAI 兼容接口；API Key 保存后掩码显示。
3. 3

   按需开启 thinking 开关，并设置 temperature（0–2，默认 0.3）。

   • ·开启 thinking 后，思考过程会以可折叠「思考过程」展示。
4. 4

   点击「测试会话」验证 LLM 连通性。

   • ·测试会发一个最小请求，并给出可读错误（401/网络/404）。
5. 5

   如需查看 Admin 菜单或发布联动，填写「Admin 地址」。

   • ·留空默认 http://localhost:3101；Admin 与 LLM 可独立保存。

4. 对话式创建 Skill

核心流程：用自然语言描述需求，AI 产出文件后自动建 Skill。

1. 1

   点击「新会话」或进入首页，开始一个草稿会话。

   • ·任意时刻最多保留一个空草稿，避免重复创建。
2. 2

   在输入框描述你要的 Skill。

   • ·例如：「我需要一个查询快递物流的技能，输入单号返回轨迹表格」。
3. 3

   发送后 AI 生成 SKILL.md、manifest.json 与脚本文件。

   • ·产出文件后，草稿会话会自动转为以 manifest.id 命名的 Skill 会话。
4. 4

   继续对话提出修改意见，AI 会基于现有文件增量修改。

   • ·多轮上下文会注入当前文件内容，便于精准修改。
5. 5

   侧栏会生成对应会话，tab 标题显示 Skill id；草稿显示内容概要或「新对话」。

   • ·会话按更新时间排序。

5. 文件编辑

在「文件」页签查看与编辑 AI 生成的文件。

• 文件树：展示 SKILL.md、manifest.json、scripts/ 等文件。
• 新建文件：手动创建相对路径文件，如 scripts/tool.js。
• Monaco 编辑器：多 tab 编辑，未保存文件带黄点标记。
• 保存：点击保存只提交有改动的文件。
• 预览：查看 Markdown 的渲染效果。

1. 1

   切换到「文件」页签。

   • ·文件树与编辑器默认展示 SKILL.md。
2. 2

   点击文件打开编辑，修改后点击保存。

   • ·未保存的修改会在文件名旁显示黄点。
3. 3

   需要新增脚本时，点击「新建文件」并填写相对路径。

   • ·创建后文件为空，可在编辑器中编辑并保存。

6. 测试运行

在「测试」页签运行 Skill，验证参数与环境变量是否正确。

1. 1

   切换到「测试」页签。

   • ·参数表单从 manifest.params 自动生成；解析失败时回退为 JSON 输入。
2. 2

   填写参数。

   • ·必填项带标记；password 类型环境变量以密文输入。
3. 3

   填写环境变量（来自 manifest.env，测试时注入执行环境）。

   • ·默认值会作为 placeholder 提示。
4. 4

   点击运行，等待结果。

   • ·结果展示迭代次数与耗时；测试历史可点击恢复该次参数。

7. 查看 Admin 菜单

Studio 可只读查看 admin 菜单树，方便开发者了解卡片与分类，并在发布时选择目标场景/分类。

1. 1

   点击顶部「Admin 菜单」入口，进入 /menu 页。

   • ·也可在会话侧栏底部点击「Admin 菜单（分类与卡片）」。
2. 2

   通过场景下拉切换不同场景。

   • ·场景由 admin 配置，分类与卡片按场景隔离。
3. 3

   查看卡片状态（online/offline/placeholder）与动作类型徽标。

   • ·skill-run 卡会高亮「Studio 发布」并显示 skillName。
4. 4

   如 admin 不可达会显示 502，可点击重试。

   • ·请先在设置中确认 Admin 地址正确。

8. 卡片开发闭环

从 admin 菜单卡片可直接创建或修改对应 Skill。

• 占位卡「创建该技能」：以 cardKey 为技能名创建基础模板，并跳转 /dev 对话开发。
• 已绑定 skill 卡「修改该技能」：本地已有直接打开；否则从商店复制到工作区。
• 非技能卡（expert-chat / mcp-tool / route / 无 skillName）不显示开发入口。

1. 1

   在 /menu 页把鼠标移到卡片右上角「⋮」。

   • ·只对占位卡与已绑定 skill 的卡显示。
2. 2

   选择「创建该技能」或「修改该技能」。

   • ·创建会生成 SKILL.md 与 manifest.json 基础模板。
3. 3

   在 /dev 对话中完成开发。

   • ·修改模式若本地没有该技能，会从商店复制一份作为开发分支。
4. 4

   发布后，卡片自动回填并绑定该 Skill。

   • ·发布联动经 admin skill-sync 完成，失败不阻断发布。

9. 发布到技能商店

开发完成后，把 Skill 发布到技能商店，并可选联动到 admin 菜单卡片。

1. 1

   在 /dev 工作台点击「发布」，进入发布页。

   • ·缺少 SKILL.md 时无法发布。
2. 2

   确认 SKILL.md 预览与文件清单。

   • ·发布页左侧展示预览与全部文件。
3. 3

   填写描述与标签（逗号分隔）。

   • ·描述用于商店展示，标签便于检索。
4. 4

   选择「菜单场景」与「菜单分类」。

   • ·发布后菜单卡片会挂到所选场景的菜单树；缺省 default 与第一个可见分类。
5. 5

   点击发布。

   • ·发布会把工作区文件复制到 SKILL_STORE_DIR，排除 .studio/ 目录。
6. 6

   如商店已有同名 Skill，可选择覆盖或取消。

   • ·覆盖发布用于有意识地替换商店版本。

10. 分支与商店副本

Studio 采用「开发 = 分支、商店 = 主线、发布 = 推送合并」的心智模型。

• 从商店复制来的 Skill（from-card copied）会记录 storeBaseHash（商店版本基线）。
• 发布时若基线 hash 与商店当前一致，直接合并，无需覆盖。
• 若商店已被他人修改，返回 409 冲突，需确认 overwrite。
• 发布成功后基线前移；侧栏该 Skill 显示「商店副本」徽标。

11. 工作区与账号隔离

每个用户的 Skill 工作区相互隔离，避免多人开发互相覆盖。

• 工作区路径：~/.studio/<username>/workspace/<skill>/。
• 对话历史与草稿按用户前缀隔离，同浏览器多用户不串记录。
• 设置文件（LLM / Admin 地址）为全局机器级配置。
• 发布带作者信息，商店 manifest.author 会记录发布者。