From 0a868b82e6bbb16b228b879901cfda91c610ba4c Mon Sep 17 00:00:00 2001 From: zhaoyanchao Date: Tue, 28 Apr 2026 22:49:22 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=B0=86README.md=E6=9B=BF=E6=8D=A2?= =?UTF-8?q?=E4=B8=BA=E4=B8=AD=E6=96=87=E9=A1=B9=E7=9B=AE=E7=AE=80=E4=BB=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 移除原有英文README内容，仅保留简短中文介绍 - 添加README-old.md保存原有完整文档 - 简化项目描述，聚焦于核心信息 --- README-old.md | 210 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 212 +------------------------------------------------- 2 files changed, 212 insertions(+), 210 deletions(-) create mode 100644 README-old.md diff --git a/README-old.md b/README-old.md new file mode 100644 index 00000000..0b090077 --- /dev/null +++ b/README-old.md @@ -0,0 +1,210 @@ +# Claw Code + +

+ ultraworkers/claw-code + · + Usage + · + Rust workspace + · + Parity + · + Roadmap + · + UltraWorkers Discord +

+ +

+ + + + + Star history for ultraworkers/claw-code + + +

+ +

+ Claw Code +

+ +Claw Code is the public Rust implementation of the `claw` CLI agent harness. +The canonical implementation lives in [`rust/`](./rust), and the current source of truth for this repository is **ultraworkers/claw-code**. + +> [!IMPORTANT] +> Start with [`USAGE.md`](./USAGE.md) for build, auth, CLI, session, and parity-harness workflows. Make `claw doctor` your first health check after building, use [`rust/README.md`](./rust/README.md) for crate-level details, read [`PARITY.md`](./PARITY.md) for the current Rust-port checkpoint, and see [`docs/container.md`](./docs/container.md) for the container-first workflow. +> +> **ACP / Zed status:** `claw-code` does not ship an ACP/Zed daemon entrypoint yet. Run `claw acp` (or `claw --acp`) for the current status instead of guessing from source layout; `claw acp serve` is currently a discoverability alias only, and real ACP support remains tracked separately in `ROADMAP.md`. + +## Current repository shape + +- **`rust/`** — canonical Rust workspace and the `claw` CLI binary +- **`USAGE.md`** — task-oriented usage guide for the current product surface +- **`PARITY.md`** — Rust-port parity status and migration notes +- **`ROADMAP.md`** — active roadmap and cleanup backlog +- **`PHILOSOPHY.md`** — project intent and system-design framing +- **`src/` + `tests/`** — companion Python/reference workspace and audit helpers; not the primary runtime surface + +## Quick start + +> [!NOTE] +> [!WARNING] +> **`cargo install claw-code` installs the wrong thing.** The `claw-code` crate on crates.io is a deprecated stub that places `claw-code-deprecated.exe` — not `claw`. Running it only prints `"claw-code has been renamed to agent-code"`. **Do not use `cargo install claw-code`.** Either build from source (this repo) or install the upstream binary: +> ```bash +> cargo install agent-code # upstream binary — installs 'agent.exe' (Windows) / 'agent' (Unix), NOT 'agent-code' +> ``` +> This repo (`ultraworkers/claw-code`) is **build-from-source only** — follow the steps below. + +```bash +# 1. Clone and build +git clone https://github.com/ultraworkers/claw-code +cd claw-code/rust +cargo build --workspace + +# 2. Set your API key (Anthropic API key — not a Claude subscription) +export ANTHROPIC_API_KEY="sk-ant-..." + +# 3. Verify everything is wired correctly +./target/debug/claw doctor + +# 4. Run a prompt +./target/debug/claw prompt "say hello" +``` + +> [!NOTE] +> **Windows (PowerShell):** the binary is `claw.exe`, not `claw`. Use `.\target\debug\claw.exe` or run `cargo run -- prompt "say hello"` to skip the path lookup. + +### Windows setup + +**PowerShell is a supported Windows path.** Use whichever shell works for you. The common onboarding issues on Windows are: + +1. **Install Rust first** — download from and run the installer. Close and reopen your terminal when it finishes. +2. **Verify Rust is on PATH:** + ```powershell + cargo --version + ``` + If this fails, reopen your terminal or run the PATH setup from the Rust installer output, then retry. +3. **Clone and build** (works in PowerShell, Git Bash, or WSL): + ```powershell + git clone https://github.com/ultraworkers/claw-code + cd claw-code/rust + cargo build --workspace + ``` +4. **Run** (PowerShell — note `.exe` and backslash): + ```powershell + $env:ANTHROPIC_API_KEY = "sk-ant-..." + .\target\debug\claw.exe prompt "say hello" + ``` + +**Git Bash / WSL** are optional alternatives, not requirements. If you prefer bash-style paths (`/c/Users/you/...` instead of `C:\Users\you\...`), Git Bash (ships with Git for Windows) works well. In Git Bash, the `MINGW64` prompt is expected and normal — not a broken install. + +## Post-build: locate the binary and verify + +After running `cargo build --workspace`, the `claw` binary is built but **not** automatically installed to your system. Here's where to find it and how to verify the build succeeded. + +### Binary location + +After `cargo build --workspace` in `claw-code/rust/`: + +**Debug build (default, faster compile):** +- **macOS/Linux:** `rust/target/debug/claw` +- **Windows:** `rust/target/debug/claw.exe` + +**Release build (optimized, slower compile):** +- **macOS/Linux:** `rust/target/release/claw` +- **Windows:** `rust/target/release/claw.exe` + +If you ran `cargo build` without `--release`, the binary is in the `debug/` folder. + +### Verify the build succeeded + +Test the binary directly using its path: + +```bash +# macOS/Linux (debug build) +./rust/target/debug/claw --help +./rust/target/debug/claw doctor + +# Windows PowerShell (debug build) +.\rust\target\debug\claw.exe --help +.\rust\target\debug\claw.exe doctor +``` + +If these commands succeed, the build is working. `claw doctor` is your first health check — it validates your API key, model access, and tool configuration. + +### Optional: Add to PATH + +If you want to run `claw` from any directory without the full path, choose one of these approaches: + +**Option 1: Symlink (macOS/Linux)** +```bash +ln -s $(pwd)/rust/target/debug/claw /usr/local/bin/claw +``` +Then reload your shell and test: +```bash +claw --help +``` + +**Option 2: Use `cargo install` (all platforms)** + +Build and install to Cargo's default location (`~/.cargo/bin/`, which is usually on PATH): +```bash +# From the claw-code/rust/ directory +cargo install --path . --force + +# Then from anywhere +claw --help +``` + +**Option 3: Update shell profile (bash/zsh)** + +Add this line to `~/.bashrc` or `~/.zshrc`: +```bash +export PATH="$(pwd)/rust/target/debug:$PATH" +``` + +Reload your shell: +```bash +source ~/.bashrc # or source ~/.zshrc +claw --help +``` + +### Troubleshooting + +- **"command not found: claw"** — The binary is in `rust/target/debug/claw`, but it's not on your PATH. Use the full path `./rust/target/debug/claw` or symlink/install as above. +- **"permission denied"** — On macOS/Linux, you may need `chmod +x rust/target/debug/claw` if the executable bit isn't set (rare). +- **Debug vs. release** — If the build is slow, you're in debug mode (default). Add `--release` to `cargo build` for faster runtime, but the build itself will take 5–10 minutes. + +> [!NOTE] +> **Auth:** claw requires an **API key** (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.) — Claude subscription login is not a supported auth path. + +Run the workspace test suite after verifying the binary works: + +```bash +cd rust +cargo test --workspace +``` + +## Documentation map + +- [`USAGE.md`](./USAGE.md) — quick commands, auth, sessions, config, parity harness +- [`rust/README.md`](./rust/README.md) — crate map, CLI surface, features, workspace layout +- [`PARITY.md`](./PARITY.md) — parity status for the Rust port +- [`rust/MOCK_PARITY_HARNESS.md`](./rust/MOCK_PARITY_HARNESS.md) — deterministic mock-service harness details +- [`ROADMAP.md`](./ROADMAP.md) — active roadmap and open cleanup work +- [`PHILOSOPHY.md`](./PHILOSOPHY.md) — why the project exists and how it is operated + +## Ecosystem + +Claw Code is built in the open alongside the broader UltraWorkers toolchain: + +- [clawhip](https://github.com/Yeachan-Heo/clawhip) +- [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent) +- [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) +- [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex) +- [UltraWorkers Discord](https://discord.gg/5TUQKqFWd) + +## Ownership / affiliation disclaimer + +- This repository does **not** claim ownership of the original Claude Code source material. +- This repository is **not affiliated with, endorsed by, or maintained by Anthropic**. diff --git a/README.md b/README.md index 0b090077..7eac0ea8 100644 --- a/README.md +++ b/README.md @@ -1,210 +1,2 @@ -# Claw Code - -

- ultraworkers/claw-code - · - Usage - · - Rust workspace - · - Parity - · - Roadmap - · - UltraWorkers Discord -

- -

- - - - - Star history for ultraworkers/claw-code - - -

- -

- Claw Code -

- -Claw Code is the public Rust implementation of the `claw` CLI agent harness. -The canonical implementation lives in [`rust/`](./rust), and the current source of truth for this repository is **ultraworkers/claw-code**. - -> [!IMPORTANT] -> Start with [`USAGE.md`](./USAGE.md) for build, auth, CLI, session, and parity-harness workflows. Make `claw doctor` your first health check after building, use [`rust/README.md`](./rust/README.md) for crate-level details, read [`PARITY.md`](./PARITY.md) for the current Rust-port checkpoint, and see [`docs/container.md`](./docs/container.md) for the container-first workflow. -> -> **ACP / Zed status:** `claw-code` does not ship an ACP/Zed daemon entrypoint yet. Run `claw acp` (or `claw --acp`) for the current status instead of guessing from source layout; `claw acp serve` is currently a discoverability alias only, and real ACP support remains tracked separately in `ROADMAP.md`. - -## Current repository shape - -- **`rust/`** — canonical Rust workspace and the `claw` CLI binary -- **`USAGE.md`** — task-oriented usage guide for the current product surface -- **`PARITY.md`** — Rust-port parity status and migration notes -- **`ROADMAP.md`** — active roadmap and cleanup backlog -- **`PHILOSOPHY.md`** — project intent and system-design framing -- **`src/` + `tests/`** — companion Python/reference workspace and audit helpers; not the primary runtime surface - -## Quick start - -> [!NOTE] -> [!WARNING] -> **`cargo install claw-code` installs the wrong thing.** The `claw-code` crate on crates.io is a deprecated stub that places `claw-code-deprecated.exe` — not `claw`. Running it only prints `"claw-code has been renamed to agent-code"`. **Do not use `cargo install claw-code`.** Either build from source (this repo) or install the upstream binary: -> ```bash -> cargo install agent-code # upstream binary — installs 'agent.exe' (Windows) / 'agent' (Unix), NOT 'agent-code' -> ``` -> This repo (`ultraworkers/claw-code`) is **build-from-source only** — follow the steps below. - -```bash -# 1. Clone and build -git clone https://github.com/ultraworkers/claw-code -cd claw-code/rust -cargo build --workspace - -# 2. Set your API key (Anthropic API key — not a Claude subscription) -export ANTHROPIC_API_KEY="sk-ant-..." - -# 3. Verify everything is wired correctly -./target/debug/claw doctor - -# 4. Run a prompt -./target/debug/claw prompt "say hello" -``` - -> [!NOTE] -> **Windows (PowerShell):** the binary is `claw.exe`, not `claw`. Use `.\target\debug\claw.exe` or run `cargo run -- prompt "say hello"` to skip the path lookup. - -### Windows setup - -**PowerShell is a supported Windows path.** Use whichever shell works for you. The common onboarding issues on Windows are: - -1. **Install Rust first** — download from and run the installer. Close and reopen your terminal when it finishes. -2. **Verify Rust is on PATH:** - ```powershell - cargo --version - ``` - If this fails, reopen your terminal or run the PATH setup from the Rust installer output, then retry. -3. **Clone and build** (works in PowerShell, Git Bash, or WSL): - ```powershell - git clone https://github.com/ultraworkers/claw-code - cd claw-code/rust - cargo build --workspace - ``` -4. **Run** (PowerShell — note `.exe` and backslash): - ```powershell - $env:ANTHROPIC_API_KEY = "sk-ant-..." - .\target\debug\claw.exe prompt "say hello" - ``` - -**Git Bash / WSL** are optional alternatives, not requirements. If you prefer bash-style paths (`/c/Users/you/...` instead of `C:\Users\you\...`), Git Bash (ships with Git for Windows) works well. In Git Bash, the `MINGW64` prompt is expected and normal — not a broken install. - -## Post-build: locate the binary and verify - -After running `cargo build --workspace`, the `claw` binary is built but **not** automatically installed to your system. Here's where to find it and how to verify the build succeeded. - -### Binary location - -After `cargo build --workspace` in `claw-code/rust/`: - -**Debug build (default, faster compile):** -- **macOS/Linux:** `rust/target/debug/claw` -- **Windows:** `rust/target/debug/claw.exe` - -**Release build (optimized, slower compile):** -- **macOS/Linux:** `rust/target/release/claw` -- **Windows:** `rust/target/release/claw.exe` - -If you ran `cargo build` without `--release`, the binary is in the `debug/` folder. - -### Verify the build succeeded - -Test the binary directly using its path: - -```bash -# macOS/Linux (debug build) -./rust/target/debug/claw --help -./rust/target/debug/claw doctor - -# Windows PowerShell (debug build) -.\rust\target\debug\claw.exe --help -.\rust\target\debug\claw.exe doctor -``` - -If these commands succeed, the build is working. `claw doctor` is your first health check — it validates your API key, model access, and tool configuration. - -### Optional: Add to PATH - -If you want to run `claw` from any directory without the full path, choose one of these approaches: - -**Option 1: Symlink (macOS/Linux)** -```bash -ln -s $(pwd)/rust/target/debug/claw /usr/local/bin/claw -``` -Then reload your shell and test: -```bash -claw --help -``` - -**Option 2: Use `cargo install` (all platforms)** - -Build and install to Cargo's default location (`~/.cargo/bin/`, which is usually on PATH): -```bash -# From the claw-code/rust/ directory -cargo install --path . --force - -# Then from anywhere -claw --help -``` - -**Option 3: Update shell profile (bash/zsh)** - -Add this line to `~/.bashrc` or `~/.zshrc`: -```bash -export PATH="$(pwd)/rust/target/debug:$PATH" -``` - -Reload your shell: -```bash -source ~/.bashrc # or source ~/.zshrc -claw --help -``` - -### Troubleshooting - -- **"command not found: claw"** — The binary is in `rust/target/debug/claw`, but it's not on your PATH. Use the full path `./rust/target/debug/claw` or symlink/install as above. -- **"permission denied"** — On macOS/Linux, you may need `chmod +x rust/target/debug/claw` if the executable bit isn't set (rare). -- **Debug vs. release** — If the build is slow, you're in debug mode (default). Add `--release` to `cargo build` for faster runtime, but the build itself will take 5–10 minutes. - -> [!NOTE] -> **Auth:** claw requires an **API key** (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.) — Claude subscription login is not a supported auth path. - -Run the workspace test suite after verifying the binary works: - -```bash -cd rust -cargo test --workspace -``` - -## Documentation map - -- [`USAGE.md`](./USAGE.md) — quick commands, auth, sessions, config, parity harness -- [`rust/README.md`](./rust/README.md) — crate map, CLI surface, features, workspace layout -- [`PARITY.md`](./PARITY.md) — parity status for the Rust port -- [`rust/MOCK_PARITY_HARNESS.md`](./rust/MOCK_PARITY_HARNESS.md) — deterministic mock-service harness details -- [`ROADMAP.md`](./ROADMAP.md) — active roadmap and open cleanup work -- [`PHILOSOPHY.md`](./PHILOSOPHY.md) — why the project exists and how it is operated - -## Ecosystem - -Claw Code is built in the open alongside the broader UltraWorkers toolchain: - -- [clawhip](https://github.com/Yeachan-Heo/clawhip) -- [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent) -- [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) -- [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex) -- [UltraWorkers Discord](https://discord.gg/5TUQKqFWd) - -## Ownership / affiliation disclaimer - -- This repository does **not** claim ownership of the original Claude Code source material. -- This repository is **not affiliated with, endorsed by, or maintained by Anthropic**. +## 项目介绍 + 本项目是claude code 的rust 版本，基于 \ No newline at end of file