82 lines
3.6 KiB
Markdown
82 lines
3.6 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
SGClaw Skill Converter — Go CLI + Web tool that converts JavaScript browser scripts into SGClaw-compatible skill packages. Single-file Go application (`main.go`) with a static web frontend (`web/`).
|
|
|
|
## Build & Run
|
|
|
|
```bash
|
|
# Build
|
|
go build -o sgclaw-skill-converter.exe .
|
|
|
|
# CLI usage
|
|
go run . --js-script-path path/to/script.js --skill-name my-skill --write
|
|
|
|
# Web server
|
|
go run . --serve --host 127.0.0.1 --port 8787
|
|
|
|
# CLI with inline script
|
|
go run . --js-script-code "return {data: []}" --skill-name demo --skill-domain www.example.com --use-ai
|
|
```
|
|
|
|
No external dependencies — uses only Go standard library (`go 1.22`, zero third-party packages).
|
|
|
|
## Architecture
|
|
|
|
Everything is in `main.go` (~1100 lines). Key functions:
|
|
|
|
- **`generateSkillPackage()`** — Core conversion orchestrator. Reads JS script, resolves defaults, optionally calls AI, generates TOML/MD/notes, writes to disk.
|
|
- **`callAI()`** — Sends script metadata to GLM-5.1 (OpenAI-compatible `/chat/completions` endpoint) to auto-generate skill metadata, descriptions, and documentation.
|
|
- **`scanRisk()`** — Pattern-based security scanner checking for shell commands, network requests, XPath usage, and missing return/throw.
|
|
- **`inferArgsFromScript()`** / **`inferArtifactFields()`** — Regex-based inference of script parameters and output fields.
|
|
- **`buildSkillToml()`** / **`buildSkillMD()`** — Template generators for SKILL.toml and SKILL.md when AI is disabled.
|
|
- **`runServer()`** — HTTP server with routes: `GET /api/config`, `POST /api/convert`, static file serving from `web/`.
|
|
|
|
### Data Flow
|
|
|
|
CLI flags or Web POST payload → `generateSkillPackage()` → read/infer script metadata → optional AI enhancement → generate 5 files (SKILL.toml, SKILL.md, scripts/*.js, references/implementation-notes.md, assets/notes.md) → write to `skills/<name>/` if `--write`.
|
|
|
|
### AI Config Resolution (priority order)
|
|
|
|
1. Per-request overrides (web payload `ai_config`)
|
|
2. Environment variables: `GLM_API_KEY`, `GLM_BASE_URL`, `GLM_MODEL`, `GLM_TIMEOUT`
|
|
3. Fallback env vars: `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`
|
|
4. `~/.claude/settings.json` (reads `env`/`envs`/`environment` sections)
|
|
5. Defaults: `glm-5.1` model, `https://open.bigmodel.cn/api/paas/v4`
|
|
|
|
## Skill Package Structure
|
|
|
|
Generated output follows SGClaw conventions:
|
|
```
|
|
skills/<skill_name>/
|
|
├── SKILL.toml # Skill config (name, tools, args, kind=browser_script)
|
|
├── SKILL.md # Human-readable documentation
|
|
├── scripts/<tool>.js # The browser script (preserved as-is)
|
|
├── references/implementation-notes.md
|
|
└── assets/notes.md
|
|
```
|
|
|
|
Key constraints from the spec (`docs/superpowers/specs/skill-generator-规范.md`):
|
|
- Scripts must end with `return <payload>` or `throw Error`
|
|
- No network requests, shell commands, or XPath in scripts
|
|
- `expected_domain` is a bare hostname, declared in contract not injected into script
|
|
- CSS selectors only, no jQuery `:contains`
|
|
|
|
## Key CLI Flags
|
|
|
|
| Flag | Purpose |
|
|
|------|---------|
|
|
| `--js-script-path` | Script file path (alternative to `--js-script-code`) |
|
|
| `--js-script-code` | Inline JS code |
|
|
| `--skill-name` | Output skill name (kebab-case) |
|
|
| `--skill-domain` | Target domain (bare hostname) |
|
|
| `--tool-name` | Tool name (snake_case) |
|
|
| `--arg-spec` | Params as `k=v,k2=v2`, JSON string, or `@json_file` |
|
|
| `--preferred-mode` | `compact` (default) or `full` |
|
|
| `--write` | Write files to disk |
|
|
| `--no-ai` | Disable AI enhancement |
|
|
| `--serve` | Start web server |
|