# angler-cli

**Repository Path**: fatgrass/angler-cli

## Basic Information

- **Project Name**: angler-cli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-10
- **Last Updated**: 2025-11-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Angler CLI 源码直接运行指南

## 概述

当你需要修改 angler-cli 的代码并立即看到效果时，无需重新安装，可以使用多种方法直接运行修改后的代码。本指南提供了完整的开发模式运行方案。

## 项目结构分析

Angler CLI 使用现代 Python 项目结构：

```
angler-cli/
├── src/angler_cli/          # 源代码目录
│   ├── cli.py             # 主入口文件
│   ├── app.py             # 应用程序主类
│   └── ...                # 其他模块
├── pyproject.toml         # 项目配置文件
├── Makefile              # 构建脚本
└── run_dev.py            # 开发运行脚本（新增）
```

### 关键配置信息

- **Python 版本要求**: `>=3.13`
- **包管理器**: `uv`
- **入口点**: `angler_cli.cli:main`
- **依赖管理**: 使用 `uv sync` 同步依赖

## 运行方法

### 方法1：使用 uv 直接运行（最推荐）

```bash
# 进入项目目录
cd /path/to/angler-cli

# 确保依赖已安装
uv sync

# 直接运行修改后的代码
uv run python src/angler_cli/cli.py

# 带参数运行
uv run python src/angler_cli/cli.py --help
uv run python src/angler_cli.cli.py --shell
uv run python src/angler_cli.cli.py --verbose
```

**优点**:
- 无需额外配置
- 自动使用项目的虚拟环境
- 支持传递所有命令行参数
- 最直接和可靠的方法

### 方法2：使用 Makefile（便捷）

```bash
# 普通运行
make run

# 带详细输出的运行
make run-dev

# 查看所有可用命令
make help
```

**新增的 Makefile 目标**:
```makefile
.PHONY: run
run: ## Run angler-cli in development mode (no installation needed).
	PYTHONPATH=src uv run python -m angler_cli.cli

.PHONY: run-dev
run-dev: ## Run angler-cli with development arguments.
	PYTHONPATH=src uv run python -m angler_cli.cli --verbose
```

### 方法3：使用开发脚本

#### Python 开发脚本 (`run_dev.py`)

```python
#!/usr/bin/env python3
"""
开发模式运行脚本
直接运行修改后的 angler-cli 代码，无需重新安装
"""
import sys
from pathlib import Path

# 添加 src 目录到 Python 路径
project_root = Path(__file__).parent
src_path = project_root / "src"

if str(src_path) not in sys.path:
    sys.path.insert(0, str(src_path))

# 导入并运行主函数
from angler_cli.cli import main

if __name__ == "__main__":
    main()
```

使用方法：
```bash
# 直接运行
python run_dev.py

# 传递参数
python run_dev.py --help
python run_dev.py --shell
```

#### Shell 快速运行脚本 (`quick_run.sh`)

```bash
#!/bin/bash
# 快速运行 angler-cli 开发版本的脚本

# 获取脚本所在目录
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"

# 设置 PYTHONPATH
export PYTHONPATH="${SCRIPT_DIR}/src:${PYTHONPATH}"

# 进入项目目录
cd "$SCRIPT_DIR"

# 检查是否安装了依赖
if [ ! -d ".venv" ] && [ ! -d "venv" ]; then
    echo "依赖未安装，正在安装..."
    uv sync
fi

# 运行 angler-cli
echo "运行开发版本的 angler-cli..."
uv run python src/angler_cli/cli.py "$@"
```

使用方法：
```bash
# 给脚本添加执行权限
chmod +x quick_run.sh

# 运行
./quick_run.sh

# 传递参数
./quick_run.sh --shell --verbose
```

### 方法4：设置 PYTHONPATH

```bash
# 方法1：设置环境变量后运行
export PYTHONPATH=/path/to/angler-cli/src:$PYTHONPATH
python -m angler_cli.cli

# 方法2：一次性执行
PYTHONPATH=src python -m angler_cli.cli

# 方法3：使用绝对路径
PYTHONPATH=/absolute/path/to/angler-cli/src python -m angler_cli.cli
```

### 方法5：创建符号链接（全局可用）

```bash
# 在项目目录中创建符号链接
sudo ln -sf /path/to/angler-cli/run_dev.py /usr/local/bin/angler-dev

# 现在可以在任何地方运行
angler-dev --help
angler-dev --shell

# 如果提示权限问题，可以改为用户级别
ln -sf /path/to/angler-cli/run_dev.py ~/.local/bin/angler-dev
export PATH=$HOME/.local/bin:$PATH
```

## 开发工作流

### 1. 修改代码

查找和修改代码的示例：

```bash
# 查找包含特定字符串的文件
grep -r "要修改的字符串" src/

# 在特定文件中搜索
grep -n "特定文本" src/angler_cli/cli.py

# 编辑文件
vim src/angler_cli/ui/shell/some_file.py
```

### 2. 快速测试

```bash
# 修改后立即测试
make run

# 或者使用详细模式查看更多信息
make run-dev

# 测试特定功能
uv run python src/angler_cli/cli.py --shell --help
```

### 3. 调试技巧

```bash
# 启用详细输出
uv run python src/angler_cli/cli.py --verbose

# 查看特定模块的日志
uv run python src/angler_cli/cli.py --verbose 2>&1 | grep -i "模块名"

# 使用 Python 调试器
uv run python -m pdb src/angler_cli/cli.py
```

### 4. 代码质量检查

```bash
# 格式化代码
make format

# 检查代码质量
make check

# 运行测试
make test
```

## 常见修改场景

### 场景1：修改显示文本

```python
# 例如：修改欢迎信息
# 在 src/angler_cli/ui/shell/app.py 或相关文件中找到代码

# 修改前
echo(f"✓ Created new session: {session.id}")

# 修改后
echo(f"🚀 新会话已创建: {session.id}")
```

### 场景2：修改颜色或样式

```python
# 在 src/angler_cli/ui/ 下的相关文件中修改颜色配置
# Angler CLI 使用 Rich 库进行终端样式设置

from rich.console import Console
from rich.style import Style

console = Console()
# 修改颜色样式
success_style = Style(color="bright_green", bold=True)
console.print("✓ Success", style=success_style)
```

### 场景3：修改命令行选项

```python
# 在 src/angler_cli/cli.py 中添加或修改 Click 选项
@click.option(
    "--new-option",
    help="新的选项描述",
    type=str,
    default="default_value"
)
def main(new_option):
    pass
```

### 场景4：修改提示词

```bash
# 找到提示词文件
find src/ -name "*.md" | grep -i prompt

# 修改系统提示词
vim src/angler_cli/agents/default/system.md

# 修改工具提示词
vim src/angler_cli/tools/bash/bash.md
```

## 故障排除

### 问题1：模块导入错误

```bash
# 错误信息示例：ModuleNotFoundError: No module named 'angler_cli'

# 解决方案1：检查 PYTHONPATH
echo $PYTHONPATH

# 解决方案2：设置正确的 PYTHONPATH
export PYTHONPATH=/absolute/path/to/angler-cli/src:$PYTHONPATH

# 解决方案3：使用绝对路径运行
cd /path/to/angler-cli && PYTHONPATH=src python src/angler_cli/cli.py
```

### 问题2：依赖问题

```bash
# 错误信息示例：ModuleNotFoundError 或版本不兼容

# 重新同步依赖
uv sync --reinstall

# 清理缓存并重新安装
uv cache clean
uv sync

# 检查 Python 版本
python --version  # 应该是 3.13+
```

### 问题3：权限问题

```bash
# 错误信息示例：Permission denied

# 给脚本添加执行权限
chmod +x run_dev.py quick_run.sh

# 检查目录权限
ls -la /path/to/angler-cli/
```

### 问题4：虚拟环境问题

```bash
# 如果 uv 创建的虚拟环境有问题
rm -rf .venv
uv sync

# 或者手动指定 Python 路径
uv run python3.13 src/angler_cli/cli.py
```

## 高级用法

### 1. 热重载开发

```bash
# 安装 watchdog 用于文件监控
uv add watchdog

# 创建热重载脚本
cat > hot_reload.py << 'EOF'
import time
import subprocess
from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler

class ChangeHandler(FileSystemEventHandler):
    def on_modified(self, event):
        if event.src_path.endswith('.py'):
            print(f"文件修改: {event.src_path}")
            # 这里可以添加自动重启逻辑

if __name__ == "__main__":
    event_handler = ChangeHandler()
    observer = Observer()
    observer.schedule(event_handler, path='src/', recursive=True)
    observer.start()

    try:
        while True:
            time.sleep(1)
    except KeyboardInterrupt:
        observer.stop()
    observer.join()
EOF

# 在一个终端运行监控，另一个终端运行 angler-cli
python hot_reload.py
```

### 2. 性能分析

```bash
# 使用 cProfile 分析性能
uv run python -m cProfile -o profile.stats src/angler_cli/cli.py --help

# 查看分析结果
uv run python -c "
import pstats
p = pstats.Stats('profile.stats')
p.sort_stats('cumulative').print_stats(20)
"
```

### 3. 内存使用分析

```bash
# 使用 memory_profiler（需要先安装）
uv add memory-profiler

# 分析内存使用
uv run python -m memory_profiler src/angler_cli/cli.py
```

## 测试建议

### 1. 单元测试

```bash
# 运行特定测试
uv run pytest tests/test_specific_file.py -v

# 运行所有测试
make test

# 带覆盖率报告
uv run pytest tests --cov=src/angler_cli
```

### 2. 集成测试

```bash
# 运行 AI 集成测试
make ai-test

# 手动集成测试
echo "测试命令" | uv run python src/angler_cli/cli.py
```

### 3. 端到端测试

```bash
# 创建测试脚本
cat > test_e2e.sh << 'EOF'
#!/bin/bash
echo "开始端到端测试..."

# 测试基本功能
echo "help" | uv run python src/angler_cli/cli.py

# 测试文件操作
echo "ls" | uv run python src/angler_cli.cli.py --print

echo "端到端测试完成"
EOF

chmod +x test_e2e.sh
./test_e2e.sh
```

## 生产环境考虑

虽然这些方法主要用于开发，但也可以用于生产环境的临时测试：

```bash
# 创建生产环境测试脚本
cat > test_production.sh << 'EOF'
#!/bin/bash
set -e

echo "生产环境测试模式"
cd /path/to/angler-cli

export PYTHONPATH=src
export ANGLER_ENV=production

# 运行基本功能测试
uv run python src/angler_cli/cli.py --help

echo "生产环境测试完成"
EOF

chmod +x test_production.sh
./test_production.sh
```

## 最佳实践

### 1. 开发环境设置

```bash
# 在 .bashrc 或 .zshrc 中添加别名
alias angler-dev='cd /path/to/angler-cli && make run'
alias angler-dev-verbose='cd /path/to/angler-cli && make run-dev'
```

### 2. Git 工作流

```bash
# 创建开发分支
git checkout -b feature/new-feature

# 修改代码并测试
vim src/angler_cli/some_file.py
make run

# 提交更改
git add .
git commit -m "feat: 修改显示文本"
```

### 3. 代码审查

```bash
# 运行代码检查
make check

# 格式化代码
make format

# 确保测试通过
make test
```

## 总结

使用这些方法，你可以：

✅ **立即看到代码修改效果** - 无需重新安装
✅ **快速迭代开发** - 修改 → 运行 → 测试的快速循环
✅ **保持开发环境整洁** - 使用项目特定的虚拟环境
✅ **支持调试** - 可以使用 Python 调试器和详细日志
✅ **灵活的参数传递** - 支持所有命令行参数

最推荐的方法是使用 `uv run python src/angler_cli/cli.py` 或 `make run`，因为它们最简单、可靠，且与项目的构建系统集成良好。

这样你就可以专注于代码修改，而不用担心复杂的安装和配置问题了！