555 lines
12 KiB
Markdown
555 lines
12 KiB
Markdown
# 入口脚本设计
|
||
|
||
## 一、概述
|
||
|
||
### 1.1 设计目标
|
||
|
||
提供跨平台的统一命令行入口，使用户可以通过 `aide <command>` 的方式调用所有功能。
|
||
|
||
### 1.2 入口脚本清单
|
||
|
||
| 脚本 | 平台 | 说明 |
|
||
|------|------|------|
|
||
| `aide.sh` | Linux/macOS | Shell 脚本入口 |
|
||
| `aide.bat` | Windows | 批处理脚本入口 |
|
||
| `main.py` | 所有平台 | Python 主程序 |
|
||
|
||
---
|
||
|
||
## 二、aide.sh 设计（Linux/macOS）
|
||
|
||
### 2.1 功能要求
|
||
|
||
1. **定位 Python**：查找可用的 Python 3.10+ 解释器
|
||
2. **定位脚本目录**：确定 main.py 的位置
|
||
3. **传递参数**：将所有命令行参数传递给 Python 程序
|
||
4. **处理错误**：Python 未找到时给出明确提示
|
||
|
||
### 2.2 实现示例
|
||
|
||
```bash
|
||
#!/usr/bin/env bash
|
||
# Aide 命令行工具入口脚本（Linux/macOS）
|
||
# 版本: 1.0
|
||
|
||
set -e # 遇到错误立即退出
|
||
|
||
# 获取脚本所在目录
|
||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||
|
||
# Python 主程序路径
|
||
MAIN_PY="${SCRIPT_DIR}/main.py"
|
||
|
||
# 查找 Python 解释器
|
||
find_python() {
|
||
# 尝试查找 Python 3.10+
|
||
for cmd in python3.12 python3.11 python3.10 python3 python; do
|
||
if command -v "$cmd" &> /dev/null; then
|
||
# 检查版本
|
||
version=$("$cmd" -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
|
||
major=$(echo "$version" | cut -d. -f1)
|
||
minor=$(echo "$version" | cut -d. -f2)
|
||
|
||
if [ "$major" -eq 3 ] && [ "$minor" -ge 10 ]; then
|
||
echo "$cmd"
|
||
return 0
|
||
fi
|
||
fi
|
||
done
|
||
|
||
return 1
|
||
}
|
||
|
||
# 查找 Python
|
||
PYTHON=$(find_python)
|
||
|
||
if [ -z "$PYTHON" ]; then
|
||
echo "✗ Python 3.10+ 未找到" >&2
|
||
echo " 建议: 安装 Python 3.10 或更高版本" >&2
|
||
echo " 文档: https://www.python.org/downloads/" >&2
|
||
exit 3
|
||
fi
|
||
|
||
# 检查 main.py 是否存在
|
||
if [ ! -f "$MAIN_PY" ]; then
|
||
echo "✗ 找不到 main.py" >&2
|
||
echo " 位置: $MAIN_PY" >&2
|
||
exit 1
|
||
fi
|
||
|
||
# 执行 Python 程序
|
||
exec "$PYTHON" "$MAIN_PY" "$@"
|
||
```
|
||
|
||
### 2.3 安装方式
|
||
|
||
```bash
|
||
# 方式1：添加到 PATH
|
||
export PATH="/path/to/aide:$PATH"
|
||
|
||
# 方式2：创建符号链接
|
||
ln -s /path/to/aide/aide.sh /usr/local/bin/aide
|
||
|
||
# 方式3：添加别名
|
||
alias aide='/path/to/aide/aide.sh'
|
||
```
|
||
|
||
---
|
||
|
||
## 三、aide.bat 设计（Windows）
|
||
|
||
### 3.1 功能要求
|
||
|
||
1. **定位 Python**：查找可用的 Python 3.10+ 解释器
|
||
2. **定位脚本目录**：确定 main.py 的位置
|
||
3. **传递参数**：将所有命令行参数传递给 Python 程序
|
||
4. **处理错误**：Python 未找到时给出明确提示
|
||
|
||
### 3.2 实现示例
|
||
|
||
```batch
|
||
@echo off
|
||
REM Aide 命令行工具入口脚本（Windows）
|
||
REM 版本: 1.0
|
||
|
||
setlocal enabledelayedexpansion
|
||
|
||
REM 获取脚本所在目录
|
||
set "SCRIPT_DIR=%~dp0"
|
||
|
||
REM Python 主程序路径
|
||
set "MAIN_PY=%SCRIPT_DIR%main.py"
|
||
|
||
REM 查找 Python 解释器
|
||
set "PYTHON="
|
||
for %%p in (python3.12 python3.11 python3.10 python3 python py) do (
|
||
where %%p >nul 2>&1
|
||
if !errorlevel! equ 0 (
|
||
REM 检查版本
|
||
for /f "delims=" %%v in ('%%p -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')"') do (
|
||
set "version=%%v"
|
||
)
|
||
|
||
REM 解析版本号
|
||
for /f "tokens=1,2 delims=." %%a in ("!version!") do (
|
||
set "major=%%a"
|
||
set "minor=%%b"
|
||
)
|
||
|
||
REM 检查是否满足要求（3.10+）
|
||
if !major! equ 3 if !minor! geq 10 (
|
||
set "PYTHON=%%p"
|
||
goto :found
|
||
)
|
||
)
|
||
)
|
||
|
||
:found
|
||
if "%PYTHON%"=="" (
|
||
echo ✗ Python 3.10+ 未找到 >&2
|
||
echo 建议: 安装 Python 3.10 或更高版本 >&2
|
||
echo 文档: https://www.python.org/downloads/ >&2
|
||
exit /b 3
|
||
)
|
||
|
||
REM 检查 main.py 是否存在
|
||
if not exist "%MAIN_PY%" (
|
||
echo ✗ 找不到 main.py >&2
|
||
echo 位置: %MAIN_PY% >&2
|
||
exit /b 1
|
||
)
|
||
|
||
REM 执行 Python 程序
|
||
"%PYTHON%" "%MAIN_PY%" %*
|
||
exit /b %errorlevel%
|
||
```
|
||
|
||
### 3.3 安装方式
|
||
|
||
```batch
|
||
REM 方式1：添加到 PATH
|
||
set PATH=C:\path\to\aide;%PATH%
|
||
|
||
REM 方式2：创建批处理文件到系统目录
|
||
copy aide.bat C:\Windows\System32\aide.bat
|
||
```
|
||
|
||
---
|
||
|
||
## 四、main.py 设计
|
||
|
||
### 4.1 功能要求
|
||
|
||
1. **命令分发**：根据第一个参数分发到对应的命令处理函数
|
||
2. **参数解析**：解析命令行参数
|
||
3. **错误处理**：统一的错误处理和退出码
|
||
4. **帮助信息**：提供 `--help` 和 `--version` 支持
|
||
|
||
### 4.2 实现框架
|
||
|
||
```python
|
||
#!/usr/bin/env python3
|
||
"""
|
||
Aide 命令行工具主程序
|
||
版本: 1.0
|
||
"""
|
||
|
||
import sys
|
||
from pathlib import Path
|
||
|
||
# 添加 src 目录到 Python 路径
|
||
SCRIPT_DIR = Path(__file__).parent
|
||
sys.path.insert(0, str(SCRIPT_DIR))
|
||
|
||
from core.output import ok, warn, err, info
|
||
from commands.init import cmd_init
|
||
from commands.env import cmd_env
|
||
from commands.config_cmd import cmd_config
|
||
|
||
|
||
VERSION = "1.0.0"
|
||
|
||
|
||
def show_help():
|
||
"""显示帮助信息"""
|
||
help_text = """Aide - AI 辅助开发工作流工具
|
||
|
||
用法:
|
||
aide <command> [options]
|
||
|
||
命令:
|
||
init 初始化 .aide 目录和配置文件
|
||
env ensure 检测并修复项目开发环境
|
||
env ensure --runtime 检测 aide 运行时环境
|
||
config get <key> 获取配置值
|
||
config set <key> <value> 设置配置值
|
||
|
||
选项:
|
||
-h, --help 显示帮助信息
|
||
-v, --version 显示版本信息
|
||
|
||
示例:
|
||
aide init
|
||
aide env ensure
|
||
aide config get task.source
|
||
aide config set task.source "new-task.md"
|
||
|
||
文档: https://github.com/your-org/aide
|
||
"""
|
||
print(help_text)
|
||
|
||
|
||
def show_version():
|
||
"""显示版本信息"""
|
||
print(f"Aide v{VERSION}")
|
||
|
||
|
||
def main():
|
||
"""主函数"""
|
||
# 解析参数
|
||
args = sys.argv[1:]
|
||
|
||
# 无参数或帮助
|
||
if not args or args[0] in ["-h", "--help", "help"]:
|
||
show_help()
|
||
return 0
|
||
|
||
# 版本信息
|
||
if args[0] in ["-v", "--version", "version"]:
|
||
show_version()
|
||
return 0
|
||
|
||
# 获取命令
|
||
command = args[0]
|
||
|
||
try:
|
||
# 命令分发
|
||
if command == "init":
|
||
return cmd_init(args[1:])
|
||
elif command == "env":
|
||
return cmd_env(args[1:])
|
||
elif command == "config":
|
||
return cmd_config(args[1:])
|
||
else:
|
||
err(
|
||
f"未知命令: {command}",
|
||
[
|
||
"可用命令: init, env, config",
|
||
"使用 'aide --help' 查看帮助"
|
||
]
|
||
)
|
||
return 2
|
||
|
||
except KeyboardInterrupt:
|
||
print("\n")
|
||
info("操作已取消")
|
||
return 130 # 128 + SIGINT(2)
|
||
|
||
except Exception as e:
|
||
err(
|
||
"命令执行失败",
|
||
[
|
||
f"原因: {str(e)}",
|
||
"使用 'aide --help' 查看帮助"
|
||
]
|
||
)
|
||
return 1
|
||
|
||
|
||
if __name__ == "__main__":
|
||
sys.exit(main())
|
||
```
|
||
|
||
### 4.3 命令处理函数接口
|
||
|
||
每个命令处理函数应该遵循以下接口：
|
||
|
||
```python
|
||
def cmd_<command>(args: list[str]) -> int:
|
||
"""命令处理函数
|
||
|
||
Args:
|
||
args: 命令参数列表（不包含命令本身）
|
||
|
||
Returns:
|
||
退出码（0 表示成功）
|
||
"""
|
||
pass
|
||
```
|
||
|
||
---
|
||
|
||
## 五、参数解析
|
||
|
||
### 5.1 简单参数解析
|
||
|
||
对于简单的命令，可以手动解析参数：
|
||
|
||
```python
|
||
def cmd_env(args: list[str]) -> int:
|
||
"""env 命令处理"""
|
||
if not args:
|
||
err("缺少子命令", ["使用 'aide env ensure' 检测环境"])
|
||
return 2
|
||
|
||
subcommand = args[0]
|
||
|
||
if subcommand == "ensure":
|
||
# 检查 --runtime 参数
|
||
runtime_only = "--runtime" in args
|
||
return env_ensure(runtime_only=runtime_only)
|
||
else:
|
||
err(f"未知子命令: {subcommand}", ["可用子命令: ensure"])
|
||
return 2
|
||
```
|
||
|
||
### 5.2 使用 argparse（可选）
|
||
|
||
对于复杂的命令，可以使用 argparse：
|
||
|
||
```python
|
||
import argparse
|
||
|
||
def cmd_config(args: list[str]) -> int:
|
||
"""config 命令处理"""
|
||
parser = argparse.ArgumentParser(
|
||
prog="aide config",
|
||
description="配置管理"
|
||
)
|
||
|
||
subparsers = parser.add_subparsers(dest="subcommand")
|
||
|
||
# get 子命令
|
||
parser_get = subparsers.add_parser("get", help="获取配置值")
|
||
parser_get.add_argument("key", help="配置键")
|
||
|
||
# set 子命令
|
||
parser_set = subparsers.add_parser("set", help="设置配置值")
|
||
parser_set.add_argument("key", help="配置键")
|
||
parser_set.add_argument("value", help="配置值")
|
||
|
||
try:
|
||
parsed = parser.parse_args(args)
|
||
except SystemExit:
|
||
return 2
|
||
|
||
if parsed.subcommand == "get":
|
||
return config_get(parsed.key)
|
||
elif parsed.subcommand == "set":
|
||
return config_set(parsed.key, parsed.value)
|
||
else:
|
||
parser.print_help()
|
||
return 2
|
||
```
|
||
|
||
---
|
||
|
||
## 六、错误处理
|
||
|
||
### 6.1 异常捕获
|
||
|
||
```python
|
||
def main():
|
||
"""主函数"""
|
||
try:
|
||
# 命令执行
|
||
return execute_command()
|
||
|
||
except KeyboardInterrupt:
|
||
# Ctrl+C 中断
|
||
print("\n")
|
||
info("操作已取消")
|
||
return 130
|
||
|
||
except FileNotFoundError as e:
|
||
# 文件不存在
|
||
err("文件不存在", [f"路径: {e.filename}"])
|
||
return 5
|
||
|
||
except PermissionError as e:
|
||
# 权限错误
|
||
err("权限不足", [f"路径: {e.filename}"])
|
||
return 1
|
||
|
||
except Exception as e:
|
||
# 其他错误
|
||
err("命令执行失败", [f"原因: {str(e)}"])
|
||
return 1
|
||
```
|
||
|
||
### 6.2 退出码规范
|
||
|
||
| 退出码 | 含义 |
|
||
|-------|------|
|
||
| 0 | 成功 |
|
||
| 1 | 一般错误 |
|
||
| 2 | 参数错误 |
|
||
| 3 | 环境错误 |
|
||
| 4 | 配置错误 |
|
||
| 5 | 文件错误 |
|
||
| 130 | 用户中断（Ctrl+C） |
|
||
|
||
---
|
||
|
||
## 七、测试
|
||
|
||
### 7.1 入口脚本测试
|
||
|
||
```bash
|
||
# 测试 aide.sh
|
||
./aide.sh --version
|
||
./aide.sh --help
|
||
./aide.sh init
|
||
./aide.sh env ensure
|
||
|
||
# 测试 aide.bat（Windows）
|
||
aide.bat --version
|
||
aide.bat --help
|
||
aide.bat init
|
||
aide.bat env ensure
|
||
```
|
||
|
||
### 7.2 main.py 测试
|
||
|
||
```python
|
||
def test_main_help(capsys):
|
||
"""测试帮助信息"""
|
||
sys.argv = ["aide", "--help"]
|
||
result = main()
|
||
|
||
assert result == 0
|
||
captured = capsys.readouterr()
|
||
assert "用法:" in captured.out
|
||
|
||
def test_main_version(capsys):
|
||
"""测试版本信息"""
|
||
sys.argv = ["aide", "--version"]
|
||
result = main()
|
||
|
||
assert result == 0
|
||
captured = capsys.readouterr()
|
||
assert "Aide v" in captured.out
|
||
|
||
def test_main_unknown_command(capsys):
|
||
"""测试未知命令"""
|
||
sys.argv = ["aide", "unknown"]
|
||
result = main()
|
||
|
||
assert result == 2
|
||
captured = capsys.readouterr()
|
||
assert "未知命令" in captured.out
|
||
```
|
||
|
||
---
|
||
|
||
## 八、安装和分发
|
||
|
||
### 8.1 目录结构
|
||
|
||
```
|
||
aide/
|
||
├── aide.sh # Linux/macOS 入口
|
||
├── aide.bat # Windows 入口
|
||
├── main.py # Python 主程序
|
||
├── core/ # 核心模块
|
||
├── commands/ # 命令实现
|
||
└── utils/ # 工具函数
|
||
```
|
||
|
||
### 8.2 安装脚本（可选）
|
||
|
||
```bash
|
||
#!/usr/bin/env bash
|
||
# install.sh - Aide 安装脚本
|
||
|
||
set -e
|
||
|
||
INSTALL_DIR="${HOME}/.local/bin"
|
||
|
||
# 创建安装目录
|
||
mkdir -p "$INSTALL_DIR"
|
||
|
||
# 复制文件
|
||
cp -r aide "$INSTALL_DIR/"
|
||
|
||
# 创建符号链接
|
||
ln -sf "$INSTALL_DIR/aide/aide.sh" "$INSTALL_DIR/aide"
|
||
|
||
# 添加到 PATH
|
||
if ! echo "$PATH" | grep -q "$INSTALL_DIR"; then
|
||
echo "export PATH=\"$INSTALL_DIR:\$PATH\"" >> ~/.bashrc
|
||
echo "✓ 已添加到 PATH"
|
||
echo " 请运行: source ~/.bashrc"
|
||
fi
|
||
|
||
echo "✓ Aide 安装完成"
|
||
echo " 使用 'aide --help' 查看帮助"
|
||
```
|
||
|
||
---
|
||
|
||
## 九、总结
|
||
|
||
### 9.1 核心要点
|
||
|
||
1. 提供跨平台的统一入口
|
||
2. 自动查找合适的 Python 解释器
|
||
3. 统一的命令分发和错误处理
|
||
4. 清晰的帮助和版本信息
|
||
|
||
### 9.2 实现检查清单
|
||
|
||
- [ ] 实现 aide.sh（Linux/macOS）
|
||
- [ ] 实现 aide.bat（Windows）
|
||
- [ ] 实现 main.py 命令分发
|
||
- [ ] 实现帮助和版本信息
|
||
- [ ] 实现错误处理和退出码
|
||
- [ ] 编写入口脚本测试
|
||
- [ ] 验证跨平台兼容性
|
||
- [ ] 编写安装脚本（可选）
|
||
|
||
---
|
||
|
||
**版本**：v1.0
|
||
**更新日期**：2025-12-13
|