sam/PhoneWork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
PhoneWork/CLAUDE.md
Yuyao Huang ba1b5b76c6 docs(claude): add SDK documentation and test examples 
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
2026-04-01 08:18:33 +08:00

2.2 KiB
Raw Blame History

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

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.