Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs(plugins): make the tool_name/skill-icon contract unmissable; lock it with a test
trohitg2e1e334ad912
diff --git a/docs-internal/node_creation.md b/docs-internal/node_creation.mdindex 0a7e6acd..77799fb9 100644--- a/docs-internal/node_creation.md+++ b/docs-internal/node_creation.md@@ -207,6 +207,7 @@ What you **do** still write:- Drop `icon.svg` (or `icon_<nodeType>.svg` for multi-node folders) and `meta.json` (`{"color": "#xxx"}`) inside the plugin folder. The class-attribute icon/color override was removed in F1 — declaring `icon` or `color` as class attrs has no effect.- An entry in `server/nodes/visuals.json` ONLY if you want an emoji or `lobehub:<brand>` icon (no folder SVG). Post-F1/F7 visuals.json carries zero `asset:<key>` values.+- A **lowercase alias entry in `visuals.json` keyed by the LLM `tool_name`** whenever you set `tool_name` to something other than `<snake_case_of_node_type>` AND ship a paired skill. The skill icon resolver maps the SKILL.md `allowed-tools` token (= the tool name) through snake→camel into `visuals.json`; a custom tool name misses the node-type key and the Master Skill row renders a blank icon. The alias carries the same icon plus the plugin's `meta.json` color — precedent: `"github": {"icon": "lobehub:Github", "color": "#8250df"}`, `"vercel": {"icon": "lobehub:Vercel", "color": "#666666"}`. Locked by `server/tests/test_skill_icon_resolution.py`.- An entry in `server/nodes/groups.py` if you introduce a new palette group.## Where to look nextdiff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.mdindex 5cb784ef..b96ea7a9 100644--- a/docs-internal/plugin_system.md+++ b/docs-internal/plugin_system.md@@ -1300,6 +1300,23 @@ registered. Stick to `<snake_case_of_node_type>` unless you'reprepared to maintain alias entries in `visuals.json`. See[`server/skills/GUIDE.md → Tool naming`](../server/skills/GUIDE.md#tool-naming--snake_case--camelcase-contract).+This is not hypothetical: `githubAction` / `vercelAction` deliberately+use the short LLM tool names `github` / `vercel`, and their Master+Skill rows shipped with blank icons until lowercase alias entries were+added. The alias must carry BOTH `icon` and `color` — color normally+comes from the plugin's `meta.json`, which is keyed by node type and+therefore also misses for a custom tool name:++```json+"github": { "icon": "lobehub:Github", "color": "#8250df" },+"vercel": { "icon": "lobehub:Vercel", "color": "#666666" }+```++The invariant is locked by+`server/tests/test_skill_icon_resolution.py` — every shipped skill must+resolve a non-empty icon, so a new plugin/skill pairing that breaks+this contract fails CI instead of shipping a blank row.+### When to use the frameworkUse it for any new event-source plugin:diff --git a/server/nodes/README.md b/server/nodes/README.mdindex b511be10..e759bda1 100644--- a/server/nodes/README.md+++ b/server/nodes/README.md@@ -347,6 +347,19 @@ Full reference: [docs-internal/plugin_system.md → "Self-contained plugin folde`model_dump(by_alias=True)`. `displayOptions.show["driver_field"]` mustmatch a property name in the same `Params` class — the frontend'svisibility evaluator looks up that exact key.+- **A custom `tool_name` breaks the paired skill's icon unless you add a+ `visuals.json` alias.** The skill icon resolver+ (`SkillLoader._parse_skill_metadata`) maps each SKILL.md+ `allowed-tools` token — which is the LLM tool name — through+ snake→camel into a `visuals.json` lookup. Keep `tool_name =+ "<snake_case_of_node_type>"` and this just works. If you deliberately+ pick a short brand name (`github` for `githubAction`, `vercel` for+ `vercelAction`), you MUST add a `visuals.json` entry keyed by that+ tool name carrying the same icon plus the plugin's `meta.json` color:+ `"github": {"icon": "lobehub:Github", "color": "#8250df"}`. Otherwise+ the Master Skill row renders a blank icon and no color. Locked by+ `tests/test_skill_icon_resolution.py` (every shipped skill must+ resolve a non-empty icon).- **LLM tool schemas must be flat.** If your Params uses nestedPydantic models or `Union`, the LLM-schema emission will add `$defs`and fail the invariant. Keep tool-facing Params flat; move nesteddiff --git a/server/skills/GUIDE.md b/server/skills/GUIDE.mdindex cf1ae274..928ca10d 100644--- a/server/skills/GUIDE.md+++ b/server/skills/GUIDE.md@@ -136,6 +136,8 @@ The skill resolver (`SkillLoader._parse_skill_metadata`) takes each `allowed-too**Common pitfall:** picking a "creative" LLM tool name that doesn't snake-back to the node type. For example, calling a `stripeAction` node's tool `stripe_cli` (because it wraps a CLI) breaks the convention — `stripe_cli` snakes to `stripeCli`, not `stripeAction`, so `visuals.json` lookup fails. Stick to `<node_type_in_snake_case>` unless you're prepared to also add an alias entry to `visuals.json`.+**If you do keep a short tool name, the alias entry is mandatory, not optional.** Real precedent: `githubAction` / `vercelAction` use the tool names `github` / `vercel`, and their skills rendered blank Master Skill rows until `visuals.json` gained lowercase alias entries keyed by the tool name. The alias must carry both `icon` and `color` (the color fallback via the plugin's `meta.json` is keyed by node type, so it misses too): `"github": {"icon": "lobehub:Github", "color": "#8250df"}`. Every shipped skill must resolve a non-empty icon — locked by `server/tests/test_skill_icon_resolution.py`, so a mismatch fails CI with a message pointing back here.+## Optional Supporting FilesSkills can include additional files that are loaded alongside the main instructions:diff --git a/server/tests/test_skill_icon_resolution.py b/server/tests/test_skill_icon_resolution.pynew file mode 100644index 00000000..0c457ef3--- /dev/null+++ b/server/tests/test_skill_icon_resolution.py@@ -0,0 +1,65 @@+"""Every shipped skill must resolve a non-empty icon.++The Master Skill panel derives each skill row's icon from its SKILL.md+``allowed-tools`` token: ``SkillLoader._parse_skill_metadata`` runs the+token through snake -> camel and looks the result up in ``visuals.json``+(or the plugin folder's ``icon.svg`` via the node-type registry). When a+plugin's LLM ``tool_name`` differs from ``<snake_case_of_node_type>``+(github, vercel), that lookup silently misses unless a lowercase alias+entry keyed by the tool name exists in ``visuals.json`` — the Master+Skill row then renders a blank icon. This is the silent-miss case the+naming contract in docs-internal/plugin_system.md ("Tool / skill /+visuals naming contract") warns about.++This suite locks the invariant so a new skill/plugin pairing that breaks+the contract fails CI instead of shipping a blank Master Skill row.+Fix options when a test here fails:++1. Name the plugin's ``tool_name`` ``<snake_case_of_node_type>`` so the+ skill's ``allowed-tools`` token resolves through the node-type key.+2. Keep the short tool name and add a ``visuals.json`` alias entry keyed+ by it, carrying the same icon plus the plugin's ``meta.json`` color —+ precedent: ``"github": {"icon": "lobehub:Github", "color": "#8250df"}``.+3. Orphan skills (no backing node) declare inline ``metadata.icon`` /+ ``metadata.color`` in the SKILL.md frontmatter.+"""++from pathlib import Path++import pytest++from services.skill_loader import SkillLoader++SKILLS_DIR = Path(__file__).resolve().parents[1] / "skills"+SKILL_MDS = sorted(SKILLS_DIR.glob("*/*/SKILL.md"))++_loader = SkillLoader()+++def test_skill_corpus_discovered() -> None:+ """Guard the glob itself — a layout change must not silently skip skills."""+ assert len(SKILL_MDS) >= 60, (+ f"Only {len(SKILL_MDS)} SKILL.md files matched "+ f"{SKILLS_DIR}/*/*/SKILL.md — the skills layout moved and this "+ "suite's glob needs updating."+ )+++ "skill_md",+ SKILL_MDS,+ ids=lambda p: f"{p.parent.parent.name}/{p.parent.name}",+)+def test_skill_resolves_icon(skill_md: Path) -> None:+ meta = _loader._parse_skill_metadata(skill_md)+ resolved = meta.metadata or {}+ assert resolved.get("icon"), (+ f"{skill_md.relative_to(SKILLS_DIR.parent)} resolves an EMPTY icon "+ f"(allowed-tools={meta.allowed_tools!r}). The Master Skill row will "+ "render blank. Either name the plugin's tool_name "+ "<snake_case_of_node_type>, add a visuals.json alias entry keyed by "+ "the tool name (icon + color, like the \"github\"/\"vercel\" "+ "entries), or declare inline metadata.icon for orphan skills. See "+ "docs-internal/plugin_system.md -> Tool / skill / visuals naming "+ "contract."+ )