Add OpenClaw skills, platform kit, and template docs
Made-with: Cursor
This commit is contained in:
112
CLAUDE.md
Normal file
112
CLAUDE.md
Normal file
@@ -0,0 +1,112 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## What This Repo Is
|
||||
|
||||
**OpenClaw** is a monorepo of installable "Skills" (plugins) for the Claw agent hosting platform (深圳匠厂科技). Each subdirectory is an independent skill that ships as an encrypted ZIP to jc2009.com and gets installed by a desktop/gateway host.
|
||||
|
||||
Each skill is independently versioned and can have its own git remote (`http://120.25.191.12:3000/admin/<slug>.git`). The root `.git` tracks only the `skill-template` scaffold.
|
||||
|
||||
## Running Skills
|
||||
|
||||
No build step — all skills are plain Python 3.10+. Run directly:
|
||||
|
||||
```bash
|
||||
# Health / version check (every skill exposes these)
|
||||
python scripts/skill_main.py health
|
||||
python scripts/skill_main.py version
|
||||
|
||||
# Account manager
|
||||
python account-manager/scripts/main.py list all
|
||||
python account-manager/scripts/main.py add "搜狐号" "13800138000"
|
||||
|
||||
# Content manager
|
||||
python content-manager/scripts/main.py get <id>
|
||||
|
||||
# API key vault
|
||||
python api-key-vault/scripts/vault.py get 17track
|
||||
|
||||
# Logistics
|
||||
python logistics-tracker/scripts/main.py <tracking_number>
|
||||
|
||||
# Sohu publish
|
||||
python sohu-publisher/scripts/main.py <account_id> <article_id>
|
||||
```
|
||||
|
||||
## Releasing a Skill
|
||||
|
||||
From the skill's directory:
|
||||
|
||||
```powershell
|
||||
.\release.ps1 # tag + push
|
||||
.\release.ps1 -DryRun # preview only
|
||||
.\release.ps1 -AutoCommit -CommitMessage "Release v1.0.5"
|
||||
```
|
||||
|
||||
This delegates to `jiangchang-platform-kit/tools/release.ps1`, creates a semver git tag, and triggers the GitHub Actions workflow that encrypts scripts via PyArmor, packs a ZIP, and syncs metadata to jc2009.com.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Skill Structure
|
||||
|
||||
Every skill directory contains:
|
||||
- `SKILL.md` — YAML frontmatter (name, version, slug, category, dependencies, allowed-tools) + Markdown body with usage triggers and env requirements. **Version here must stay in sync with the git tag.**
|
||||
- `scripts/` — Python entry points
|
||||
- `release.ps1` — delegates to platform kit
|
||||
|
||||
### Environment Contract (`CLAW_*`)
|
||||
|
||||
Skills locate user data via env vars:
|
||||
|
||||
| Variable | Purpose | Dev default |
|
||||
|---|---|---|
|
||||
| `CLAW_DATA_ROOT` | User data root | `D:\claw-data` or `~/.claw-data` |
|
||||
| `CLAW_USER_ID` | Workspace ID | `_anon` |
|
||||
| `CLAW_SKILLS_ROOT` | Sibling skills dir | Parent of skill dir |
|
||||
|
||||
Legacy aliases (`JIANGCHANG_DATA_ROOT`, etc.) are still detected; prefer `CLAW_*` in new code.
|
||||
|
||||
Data path convention: `{CLAW_DATA_ROOT}/{CLAW_USER_ID}/{slug}/` (SQLite DBs, cache, temp).
|
||||
|
||||
### Skill Types
|
||||
|
||||
| Type | Pattern | Examples |
|
||||
|---|---|---|
|
||||
| A | Stateless tool | logistics-tracker |
|
||||
| B | Local persistent (SQLite) | account-manager, content-manager, api-key-vault |
|
||||
| C | Orchestrator (calls sibling skills via subprocess) | — |
|
||||
| D | Hybrid (B + C) | sohu-publisher |
|
||||
|
||||
Type C/D skills declare `dependencies.required` in SKILL.md and call siblings like:
|
||||
```python
|
||||
subprocess.run(["python", f"{skills_root}/account-manager/scripts/main.py", ...])
|
||||
```
|
||||
|
||||
### Shared Platform Kit (`jiangchang-platform-kit/`)
|
||||
|
||||
- `sdk/jiangchang_skill_core` — `EntitlementClient`, `enforce_entitlement` (license checks)
|
||||
- `.github/workflows/reusable-release-skill.yaml` — reusable CI called by every skill's release workflow
|
||||
- `tools/release.ps1` — shared release script
|
||||
|
||||
### CLI Conventions
|
||||
|
||||
- Subcommands: `health` (offline quick check, exits 0/1), `version` (JSON output), custom actions
|
||||
- Success prefix: `OK` or plain output
|
||||
- Error prefix: `ERROR:` (e.g., `ERROR:REQUIRE_LOGIN`)
|
||||
- Windows GBK fix: wrap stdout/stderr with `io.TextIOWrapper(..., encoding='utf-8')`
|
||||
|
||||
## Key Docs
|
||||
|
||||
| File | What it covers |
|
||||
|---|---|
|
||||
| `skill-template/README.md` | Onboarding, anti-patterns |
|
||||
| `skill-template/docs/RUNTIME.md` | Full env var contract and fallback behavior |
|
||||
| `skill-template/docs/SKILL_TYPES.md` | Type A–D classification checklist |
|
||||
| `skill-template/docs/PORTABILITY.md` | Cross-platform encoding, path differences |
|
||||
| `skill-template/docs/LOGGING.md` | `TimedRotatingFileHandler` setup |
|
||||
|
||||
## Known Dev-Mode Issues
|
||||
|
||||
- `account-manager/scripts/main.py` has `_ACCOUNT_MANAGER_CLI_LOCAL_DEV = True` hardcoded with a fixed data path (`D:\jiangchang-data`) and user ID — disable before releasing.
|
||||
- `toutiao-publisher` is a placeholder stub; publish logic is not yet implemented.
|
||||
Reference in New Issue
Block a user