技能共享开发容器
- 作者仓库星标 194
- 作者仓库 skills
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @JetBrains · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Docker
- 运行环境要求
- Docker
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
Execute CLI commands and tests inside the devcontainer. The host machine is macOS but the project binary is Linux — running CLI commands on the host will silently produce wrong results or fail. This skill prevents that mistake.
## When to Use This
- Running `ss` / `skillshare` commands for verification
- Running `go test`, `make test`, `make check`
- Reproducing a bug report
- Testing a feature you just implemented
- Starting the web UI dashboard
- Any command that needs the skillshare binary or Go toolchain
## When NOT to Use This
- Editing source code (do that on host via Read/Edit tools)
- Running `git` commands (git works on host)
- Running `make fmt`, `make lint` (host-safe Go toolchain commands; no container needed)
- E2E test runbooks → use `cli-e2e-test` skill instead (it handles ssenv isolation)
## Architecture: Two Layers of Isolation
```
Host (macOS)
└─ Devcontainer (Linux, Debian-based)
├─ Default HOME: /home/developer (persistent volume)
├─ Source: /workspace (bind-mount of repo root)
└─ ssenv environments: ~/.ss-envs/<name>/ (isolated HOME dirs)
```
**Devcontainer** = Linux environment with Go, git, pnpm, air (hot-reload). Source code is at `/workspace` (bind-mount of the host repo). The `ss` / `skillshare` wrapper auto-builds from source on every invocation — **no manual `make build` needed**. Edit code on the host, then immediately `docker exec` to run it; the change is picked up automatically.
**ssenv** = Isolated HOME directories within the devcontainer. Each env gets its own `~/.config/skillshare/`, `~/.claude/`, etc. Use ssenv when you need a clean state (testing init, install, sync) without polluting the container's default HOME.
## Zero-Rebuild Workflow
Source code is bind-mounted into the container at `/workspace`. The `ss` wrapper runs `go build` transparently on every invocation:
1. Edit files on host (Read/Edit tools)
2. `docker exec $CONTAINER ss <command>` — picks up your changes instantly
3. No `make build`, no restart, no rebuild step
This also applies to `go test` — tests always compile against the latest source. The Web UI backend uses `air` for hot-reload (same zero-rebuild experience).
## Entering the Devcontainer
The quickest way — one command builds, initialises, and enters the shell:
```bash
make devc # build + init + interactive shell (one step)
make devc-up # start only (no shell)
make devc-down # stop
make devc-restart # restart + re-run start-dev.sh
make devc-reset # full reset (remove volumes), then `make devc` to re-init
make devc-status # show container status
```
Works with **or without** VS Code — `make devc` handles the full lifecycle autonomously.
### Programmatic access (for `docker exec` workflows)
```bash
CONTAINER=$(docker compose -f .devcontainer/docker-compose.yml ps -q skillshare-devcontainer 2>/dev/null)
```
If `$CONTAINER` is empty, tell the user:
> Devcontainer is not running. Start it with `make devc-up`.
Then verify the binary:
```bash
docker exec $CONTAINER bash -c \
'/workspace/.devcontainer/ensure-skillshare-linux-binary.sh && ss version'
```
## Running Commands
### Simple command (uses container's default HOME)
```bash
docker exec $CONTAINER ss <command> [flags]
```
Good for: `ss version`, `ss status`, `ss list`, `ss check`, `ss audit`.
### Command with isolated HOME (clean state)
```bash
ENV_NAME="test-$(date +%s)"
docker exec $CONTAINER ssenv create "$ENV_NAME" --init
docker exec $CONTAINER ssenv enter "$ENV_NAME" -- ss status
# Cleanup when done:
docker exec $CONTAINER ssenv delete "$ENV_NAME" --force
```
Good for: testing `init`, `install`, `sync`, `uninstall` — anything that modifies config/state.
### Multi-command sequence
```bash
docker exec $CONTAINER ssenv enter "$ENV_NAME" -- bash -c '
ss install runkids/demo-skills --track --force
ss list
ss sync
'
```
Always use `bash -c '...'` for multi-command sequences inside `ssenv enter`.
### Go tests
```bash
# All tests (unit + integration)
docker exec $CONTAINER bash -c 'cd /workspace && make test'
# Unit tests only
docker exec $CONTAINER bash -c 'cd /workspace && make test-unit'
# Integration tests only
docker exec $CONTAINER bash -c 'cd /workspace && make test-int'
# Specific test
docker exec $CONTAINER bash -c 'cd /workspace && go test ./tests/integration -run TestInit_Fresh -count=1'
# Specific package
docker exec $CONTAINER bash -c 'cd /workspace && go test ./internal/install/... -count=1'
```
Always `cd /workspace` before Go commands — ssenv changes HOME which can break module resolution.
### Go tests with auth disabled
Some tests (e.g., `TestResolveToken`, `TestAuthEnv`) need auth credentials removed:
```bash
docker exec $CONTAINER bash -c '
eval "$(credential-helper --eval off)"
cd /workspace
go test ./internal/github -run TestResolveToken -count=1
eval "$(credential-helper --eval on)"
'
```
## Web UI Dashboard
```bash
# Start (global mode)
docker exec $CONTAINER ui
# Start (project mode — uses ~/demo-project)
docker exec $CONTAINER ui -p
# Stop
docker exec $CONTAINER ui stop
```
Dashboard accessible at `http://localhost:5173` (Vite dev server with HMR).
API backend at `http://localhost:19420`.
Logs: `/tmp/api-dev.log`, `/tmp/vite-dev.log`.
## ssenv Quick Reference
| Shortcut | Full form | Purpose |
|----------|-----------|---------|
| `ssnew <name>` | `ssenv create <name>` + enter | Create and enter isolated shell |
| `ssuse <name>` | `ssenv enter <name>` | Enter existing isolated shell |
| `ssrm <name>` | `ssenv delete <name> --force` | Delete environment |
| `ssls` | `ssenv list` | List all environments |
| `ssback` | `ssenv reset` | Leave isolated context |
| `sshelp` | `help` | Show all devcontainer commands |
For automation (non-interactive), prefer `ssenv enter <name> -- <command>` over `ssnew`/`ssuse` (which launch subshells).
## Ports
| Port | Service | Notes |
|------|---------|-------|
| 5173 | Vite dev server | React dashboard with HMR |
| 19420 | Go API backend | `skillshare ui` server |
| 3000 | Docusaurus | `docs` command in devcontainer |
## Common Mistakes to Avoid
1. **Running `ss` on host** — macOS binary won't match Linux container; always `docker exec`
2. **Forgetting `cd /workspace`** — Go tests fail if HOME was changed by ssenv
3. **Using `make test` on host** — builds macOS binary, then tests run against wrong arch
4. **Skipping `--init` on ssenv create** — env won't have config; most commands will fail
5. **Not cleaning up ssenv** — `ssenv delete <name> --force` after done; or ask user
6. **Running from /workspace root without -g** — the `ss` wrapper auto-redirects to `~/demo-project` in project mode; use `-g` for global or set `SKILLSHARE_DEV_ALLOW_WORKSPACE_PROJECT=1`
7. **Running `make build` before testing** — unnecessary; the `ss` wrapper auto-builds from source every time
## Rules
- **All CLI execution inside devcontainer** — no exceptions
- **Use ssenv for stateful tests** — don't pollute default HOME
- **Always verify** — run the command and check output; never assume it worked
- **Clean up** — delete ssenv environments after use (or ask user)
- **Report container ID** — set `$CONTAINER` at the start and reuse throughout
章节与文件索引
按说明文件中的顺序排列。
何时使用此功能
何时不使用此功能
架构:两层隔离
零重建工作流程
进入Dev容器
文件/命令 -> skillshare · go test · make test · make check · git · make fmt · make lint · cli-e2e-test
内容校验值 -> c76ad72761d4
当前原文的自动摘译,尚未人工审校。
何时使用此功能
运行
ss/skillshare命令进行验证 运行go test、make test、make check重现错误报告 测试刚刚实现的功能 启动 Web UI 仪表板何时不使用此功能
编辑源代码(通过读取/编辑工具在主机上执行此操作) 运行
git命令(git 在主机上运行) 运行make fmt、make lint(主机安全的 Go 工具链命令;不需要容器) E2E 测试运行手册 → 使用cli-e2e-test技能(它处理 ssenv 隔离)架构:两层隔离
Devcontainer = Linux 环境,包含 Go、git、pnpm、air(热重载)。源代码位于
/workspace(主机存储库的绑定安装)。ss/skillshare包装器在每次调用时都会从源代码自动构建 - 无需手动make build。在主机上编辑代码,然后立即docker exec运行;更改会自动生效。 ssenv = devcontainer 中的隔离主目录。每个 env 都有自己的~/.config/skillshare/、~/.claude/等。当您需要干净的状态(测试 init、安装、同步)而不污染容器的默认 HOME 时,请使用 ssenv。零重建工作流程
源代码绑定安装到位于
/workspace的容器中。ss包装器在每次调用时透明地运行go build: 在主机上编辑文件(读取/编辑工具)docker exec $CONTAINER ss <command>— 立即获取您的更改 没有make build,无需重新启动,无需重建步骤 这也适用于go test— 测试始终针对最新源进行编译。 Web UI 后端使用air进行热重载(相同的零重建体验)。进入Dev容器
最快的方法 - 一个命令构建、初始化并进入 shell:无论是否使用 VS Code,都可以使用 -
make devc自主处理整个生命周期。