ba1b5b76c6
Add comprehensive documentation for Claude Agent SDK including usage patterns, test examples, and development guide. Includes: - CLAUDE.md with project structure and quick reference - SDK test examples for query, client, and hooks - Shared test utilities for auth and tmpdir management - Detailed SDK overview and capabilities documentation
51 lines
2.2 KiB
Markdown
51 lines
2.2 KiB
Markdown
# PhoneWork — Development Guide
|
|
|
|
## Quick Reference
|
|
|
|
| Need | Where to look |
|
|
|------|---------------|
|
|
| Project architecture, deployment, bot commands | `README.md` |
|
|
| Claude Agent SDK usage patterns and tested examples | `docs/claude/` |
|
|
| SDK migration plan (subprocess → ClaudeSDKClient) | `.claude/plans/toasty-pondering-nova.md` |
|
|
| Feishu card / markdown formatting | `docs/feishu/` |
|
|
|
|
## Claude Agent SDK
|
|
|
|
When writing code that uses `claude-agent-sdk`, **first read `docs/claude/`**:
|
|
|
|
- `_sdk_test_common.py` — .env auth loading pattern (`setup_auth()`, `auth_env()`, `make_tmpdir()`)
|
|
- `test_query_read_edit.py` — `query()` one-shot: Read + Edit with `allowed_tools`
|
|
- `test_client_write_resume.py` — `ClaudeSDKClient`: Write + session resume via `resume=session_id`
|
|
- `test_hooks_audit_deny.py` — Hooks: `PostToolUse` audit + `PreToolUse` deny
|
|
|
|
### Key rules (verified by testing)
|
|
|
|
- Use `allowed_tools` for permission auto-approval. **Do not pass custom lists to `tools=`** — it causes CLI exit code 1.
|
|
- Auth: set `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN` in `.env`; pass via `ClaudeAgentOptions(env=auth_env())`. Clear `ANTHROPIC_API_KEY` to avoid auth conflicts.
|
|
- SDK does not strip ANSI escape codes from `ResultMessage.result` — handle in application layer if needed.
|
|
- On Windows, use manual `make_tmpdir()` / `remove_tmpdir()` instead of `tempfile.TemporaryDirectory()` context manager to avoid cleanup races with CLI subprocesses.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
bot/ Feishu event handling, commands, message sending
|
|
orchestrator/ LangChain agent + tools (session management, shell, files, web)
|
|
agent/ Claude Code runner, session manager, task runner, scheduler, audit
|
|
router/ Multi-host routing (public VPS side)
|
|
host_client/ Host client (behind NAT, connects to router)
|
|
shared/ Wire protocol for router ↔ host communication
|
|
docs/claude/ Claude Agent SDK examples and reference tests
|
|
docs/feishu/ Feishu API reference
|
|
```
|
|
|
|
## Running Tests
|
|
|
|
```bash
|
|
cd docs/claude
|
|
../../.venv/Scripts/python test_query_read_edit.py
|
|
../../.venv/Scripts/python test_client_write_resume.py
|
|
../../.venv/Scripts/python test_hooks_audit_deny.py
|
|
```
|
|
|
|
Requires `.env` at project root with `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN`.
|