113 lines
4.2 KiB
Markdown
113 lines
4.2 KiB
Markdown
# 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.
|