# 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.