mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-11-20 03:10:34 +00:00
fix(skills): make find-skills installer failures actionable (#8393)
* fix(skills): make find-skills installer failures actionable * fix(skills): clarify installer guidance and harden tests * docs(skills): correct installer usage header
This commit is contained in:
parent
50d04ddf71
commit
a96c9c0318
@ -68,7 +68,7 @@ vercel-labs/agent-skills@vercel-react-best-practices
|
||||
When you find relevant skills, present them to the user with:
|
||||
|
||||
1. The skill name and what it does
|
||||
2. The install command they can run
|
||||
2. The installation action for their current environment (see Step 4)
|
||||
3. A link to learn more at skills.sh
|
||||
|
||||
Example response:
|
||||
@ -77,27 +77,31 @@ Example response:
|
||||
I found a skill that might help! The "vercel-react-best-practices" skill provides
|
||||
React and Next.js performance optimization guidelines from Vercel Engineering.
|
||||
|
||||
To install it:
|
||||
bash /path/to/skill/scripts/install-skill.sh vercel-labs/agent-skills@vercel-react-best-practices
|
||||
To install it in a host DeerFlow checkout, run this command from the repository root:
|
||||
bash skills/public/find-skills/scripts/install-skill.sh vercel-labs/agent-skills@vercel-react-best-practices
|
||||
|
||||
In a DeerFlow sandbox or Web session, use the administrator .skill import flow described in Step 4.
|
||||
|
||||
Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
|
||||
```
|
||||
|
||||
### Step 4: Install the Skill
|
||||
|
||||
If the user wants to proceed, use the `install-skill.sh` script to install the skill and automatically link it to the project:
|
||||
Choose the installation path for the current environment.
|
||||
|
||||
**Inside a host DeerFlow checkout**, run [install-skill.sh](scripts/install-skill.sh) from the repository root. It installs the skill under `$HOME/.agents/skills/` and links it into that checkout's `skills/custom/` directory:
|
||||
|
||||
```bash
|
||||
bash /path/to/skill/scripts/install-skill.sh <owner/repo@skill-name>
|
||||
bash skills/public/find-skills/scripts/install-skill.sh <owner/repo@skill-name>
|
||||
```
|
||||
|
||||
For example, if the user wants to install `vercel-react-best-practices`:
|
||||
For example:
|
||||
|
||||
```bash
|
||||
bash /path/to/skill/scripts/install-skill.sh vercel-labs/agent-skills@vercel-react-best-practices
|
||||
bash skills/public/find-skills/scripts/install-skill.sh vercel-labs/agent-skills@vercel-react-best-practices
|
||||
```
|
||||
|
||||
The script will install the skill globally to `skills/custom/`
|
||||
**Inside an isolated DeerFlow sandbox or Web session**, do not run this helper. The host checkout and its writable `skills/custom/` directory are unavailable, and `/mnt/skills` is a read-only projection. Instead, provide the skill as a `.skill` archive and ask an administrator to install it through **Capability Center → Skills → My skills → Install .skill**. If the source does not provide an archive, package the downloaded skill directory first with `python /mnt/skills/public/skill-creator/scripts/package_skill.py <skill-directory> <output-directory>` or an equivalent ZIP tool. Installation uses the administrator's per-user skill storage and makes the skill available through the normal skill projection. Do not copy skill files into `/mnt/skills` or claim that writing files into the thread workspace installs a skill.
|
||||
|
||||
## Common Skill Categories
|
||||
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
#!/bin/bash
|
||||
|
||||
# Install a skill and link it to the project's skills/custom directory
|
||||
# Usage: ./skills/install-skill.sh <owner/repo@skill-name>
|
||||
# Example: ./skills/install-skill.sh vercel-labs/agent-skills@vercel-react-best-practices
|
||||
# Usage: bash skills/public/find-skills/scripts/install-skill.sh <owner/repo@skill-name>
|
||||
# Example: bash skills/public/find-skills/scripts/install-skill.sh vercel-labs/agent-skills@vercel-react-best-practices
|
||||
|
||||
set -e
|
||||
|
||||
@ -36,18 +36,26 @@ find_project_root() {
|
||||
return 1
|
||||
}
|
||||
|
||||
PROJECT_ROOT=$(find_project_root)
|
||||
|
||||
if [[ -z "$PROJECT_ROOT" ]]; then
|
||||
echo "Error: Could not find project root (deer-flow.code-workspace not found)"
|
||||
if ! PROJECT_ROOT="$(find_project_root)"; then
|
||||
printf '%s\n' \
|
||||
'Error: Could not find a DeerFlow checkout (deer-flow.code-workspace not found).' \
|
||||
"This installer only links skills into a checkout's skills/custom directory." \
|
||||
'In a sandbox or Web session, ask an administrator to install a .skill archive through Capability Center → Skills → My skills → Install .skill.' >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
SKILL_SOURCE="$HOME/.agents/skills/$SKILL_NAME"
|
||||
SKILL_TARGET="$PROJECT_ROOT/skills/custom"
|
||||
|
||||
# Step 1: Install the skill using npx
|
||||
npx skills add "$FULL_SKILL_NAME" -g -y > /dev/null 2>&1
|
||||
# Step 1: Install the skill using npx. Preserve the original quiet success path,
|
||||
# but return the command's status and output when installation fails.
|
||||
if NPX_OUTPUT="$(npx skills add "$FULL_SKILL_NAME" -g -y 2>&1)"; then
|
||||
:
|
||||
else
|
||||
NPX_STATUS=$?
|
||||
printf 'Error: npx skills add failed for %s (exit %d).\n%s\n' "$FULL_SKILL_NAME" "$NPX_STATUS" "$NPX_OUTPUT" >&2
|
||||
exit "$NPX_STATUS"
|
||||
fi
|
||||
|
||||
# Step 2: Verify installation
|
||||
if [[ ! -d "$SKILL_SOURCE" ]]; then
|
||||
|
||||
116
tests/skills/test_find_skills_install.py
Normal file
116
tests/skills/test_find_skills_install.py
Normal file
@ -0,0 +1,116 @@
|
||||
"""Offline regressions for the find-skills host-checkout installer."""
|
||||
|
||||
import os
|
||||
import subprocess
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
INSTALLER = (
|
||||
Path(__file__).resolve().parents[2]
|
||||
/ "skills/public/find-skills/scripts/install-skill.sh"
|
||||
)
|
||||
SKILL_REFERENCE = "example/repo@example-skill"
|
||||
|
||||
pytestmark = pytest.mark.skipif(
|
||||
os.name == "nt", reason="The installer and npx test doubles require Bash"
|
||||
)
|
||||
|
||||
|
||||
def _install_fake_npx(tmp_path: Path, body: str) -> Path:
|
||||
bin_dir = tmp_path / "bin"
|
||||
bin_dir.mkdir()
|
||||
executable = bin_dir / "npx"
|
||||
executable.write_text(f"#!/bin/bash\n{body}\n", encoding="utf-8", newline="\n")
|
||||
executable.chmod(0o755)
|
||||
return bin_dir
|
||||
|
||||
|
||||
def _run_installer(
|
||||
cwd: Path, home: Path, bin_dir: Path, log: Path
|
||||
) -> subprocess.CompletedProcess[str]:
|
||||
env = {
|
||||
**os.environ,
|
||||
"HOME": str(home),
|
||||
"PATH": f"{bin_dir}{os.pathsep}{os.environ['PATH']}",
|
||||
"NPX_TEST_LOG": str(log),
|
||||
}
|
||||
return subprocess.run(
|
||||
["bash", str(INSTALLER), SKILL_REFERENCE],
|
||||
check=False,
|
||||
cwd=cwd,
|
||||
env=env,
|
||||
capture_output=True,
|
||||
encoding="utf-8",
|
||||
timeout=15,
|
||||
)
|
||||
|
||||
|
||||
def test_missing_checkout_reports_actionable_error_without_calling_npx(
|
||||
tmp_path: Path,
|
||||
) -> None:
|
||||
if any(
|
||||
(parent / "deer-flow.code-workspace").is_file()
|
||||
for parent in (tmp_path, *tmp_path.parents)
|
||||
):
|
||||
pytest.skip(
|
||||
"This regression requires a temporary directory outside a DeerFlow checkout"
|
||||
)
|
||||
workspace = tmp_path / "workspace"
|
||||
workspace.mkdir()
|
||||
bin_dir = _install_fake_npx(tmp_path, 'printf called > "$NPX_TEST_LOG"\nexit 99')
|
||||
log = tmp_path / "npx-called"
|
||||
|
||||
result = _run_installer(tmp_path / "workspace", tmp_path / "home", bin_dir, log)
|
||||
|
||||
assert result.returncode == 1
|
||||
assert result.stdout == ""
|
||||
assert "Could not find a DeerFlow checkout" in result.stderr
|
||||
assert "skills/custom" in result.stderr
|
||||
assert "Install .skill" in result.stderr
|
||||
assert not log.exists()
|
||||
|
||||
|
||||
def test_npx_failure_preserves_status_and_output(tmp_path: Path) -> None:
|
||||
(tmp_path / "deer-flow.code-workspace").touch()
|
||||
bin_dir = _install_fake_npx(
|
||||
tmp_path,
|
||||
'printf "registry unavailable\\n"\nprintf "upstream timed out\\n" >&2\nexit 23',
|
||||
)
|
||||
|
||||
result = _run_installer(
|
||||
tmp_path, tmp_path / "home", bin_dir, tmp_path / "npx-called"
|
||||
)
|
||||
|
||||
assert result.stdout == ""
|
||||
assert result.stderr.splitlines() == [
|
||||
f"Error: npx skills add failed for {SKILL_REFERENCE} (exit 23).",
|
||||
"registry unavailable",
|
||||
"upstream timed out",
|
||||
]
|
||||
assert not (tmp_path / "skills/custom/example-skill").exists()
|
||||
|
||||
|
||||
def test_successful_install_links_skill_into_checkout(tmp_path: Path) -> None:
|
||||
(tmp_path / "deer-flow.code-workspace").touch()
|
||||
bin_dir = _install_fake_npx(
|
||||
tmp_path,
|
||||
'printf "%s\\n" "$@" > "$NPX_TEST_LOG"\nmkdir -p "$HOME/.agents/skills/example-skill"',
|
||||
)
|
||||
home = tmp_path / "home"
|
||||
log = tmp_path / "npx-args"
|
||||
|
||||
result = _run_installer(tmp_path, home, bin_dir, log)
|
||||
|
||||
assert result.returncode == 0, result.stdout + result.stderr
|
||||
assert result.stdout.strip() == "Skill 'example-skill' installed successfully"
|
||||
assert log.read_text(encoding="utf-8").splitlines() == [
|
||||
"skills",
|
||||
"add",
|
||||
SKILL_REFERENCE,
|
||||
"-g",
|
||||
"-y",
|
||||
]
|
||||
link = tmp_path / "skills/custom/example-skill"
|
||||
assert link.is_symlink()
|
||||
assert link.resolve() == (home / ".agents/skills/example-skill").resolve()
|
||||
Loading…
x
Reference in New Issue
Block a user