docs: 优化README文档，新增详细安装指南
- README: 重写为简洁风格，聚焦项目价值、快速启动、未来发展 - INSTALL.md: 新增完整安装指南，包含多种安装方式、配置说明、故障排除 - 改进AI友好度，提供一键安装/升级指令 - 符合用户使用习惯，提升文档可读性
This commit is contained in:
+369
@@ -0,0 +1,369 @@
|
|||||||
|
# SAP-CLI-SKILL 安装指南
|
||||||
|
|
||||||
|
本文档详细介绍如何在不同环境中安装、配置和验证 SAP-CLI-SKILL。
|
||||||
|
|
||||||
|
## 📋 目录
|
||||||
|
|
||||||
|
- [系统要求](#系统要求)
|
||||||
|
- [安装方式](#安装方式)
|
||||||
|
- [配置说明](#配置说明)
|
||||||
|
- [验证安装](#验证安装)
|
||||||
|
- [升级指南](#升级指南)
|
||||||
|
- [故障排除](#故障排除)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔧 系统要求
|
||||||
|
|
||||||
|
### Python 版本
|
||||||
|
- **最低要求**: Python 3.10+
|
||||||
|
- **推荐版本**: Python 3.11+
|
||||||
|
|
||||||
|
### 操作系统
|
||||||
|
- Windows 10/11
|
||||||
|
- macOS 10.15+
|
||||||
|
- Linux (主流发行版)
|
||||||
|
|
||||||
|
### 依赖包
|
||||||
|
- `requests >= 2.28.0`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📦 安装方式
|
||||||
|
|
||||||
|
### 方式一：Hermes Agent 安装
|
||||||
|
|
||||||
|
适用于使用 Hermes Agent 的环境。
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. 克隆仓库到 Hermes skills 目录
|
||||||
|
git clone https://gitee.com/markwury168/sap-cli-skill.git ~/AppData/Local/hermes/skills/productivity/sap-cli
|
||||||
|
|
||||||
|
# 2. 运行安装脚本（推荐一键安装）
|
||||||
|
cd ~/AppData/Local/hermes/skills/productivity/sap-cli
|
||||||
|
python scripts/setup.py all
|
||||||
|
```
|
||||||
|
|
||||||
|
**一键安装包含**：
|
||||||
|
- ✅ 安装 sap-cli 及依赖
|
||||||
|
- ✅ 交互式配置 SAP 连接
|
||||||
|
- ✅ 验证安装和连接
|
||||||
|
|
||||||
|
### 方式二：Claude Code 安装
|
||||||
|
|
||||||
|
适用于使用 Claude Code 的环境。
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. 克隆仓库到 Claude Code skills 目录
|
||||||
|
git clone https://gitee.com/markwury168/sap-cli-skill.git ~/.claude/skills/sap-cli
|
||||||
|
|
||||||
|
# 2. 运行安装脚本
|
||||||
|
cd ~/.claude/skills/sap-cli
|
||||||
|
python scripts/setup.py all
|
||||||
|
```
|
||||||
|
|
||||||
|
### 方式三：手动安装
|
||||||
|
|
||||||
|
适用于需要自定义安装的场景。
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. 克隆仓库
|
||||||
|
git clone https://gitee.com/markwury168/sap-cli-skill.git /path/to/sap-cli-skill
|
||||||
|
|
||||||
|
# 2. 安装依赖
|
||||||
|
cd /path/to/sap-cli-skill/assets
|
||||||
|
pip install requests>=2.28.0
|
||||||
|
|
||||||
|
# 3. 验证安装
|
||||||
|
python main.py --help
|
||||||
|
|
||||||
|
# 4. 配置 SAP 连接（见配置说明）
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⚙️ 配置说明
|
||||||
|
|
||||||
|
### 自动配置（推荐）
|
||||||
|
|
||||||
|
运行交互式配置脚本：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python scripts/setup.py config
|
||||||
|
```
|
||||||
|
|
||||||
|
按照提示输入：
|
||||||
|
- SAP 服务器地址 (如 `http://sap.example.com:8000`)
|
||||||
|
- SAP Client (如 `100`)
|
||||||
|
- 用户名
|
||||||
|
- 密码
|
||||||
|
|
||||||
|
### 手动配置
|
||||||
|
|
||||||
|
编辑配置文件：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 复制配置模板
|
||||||
|
cp assets/config.ini.example assets/config.ini
|
||||||
|
|
||||||
|
# 编辑配置文件
|
||||||
|
vim assets/config.ini
|
||||||
|
```
|
||||||
|
|
||||||
|
配置文件格式：
|
||||||
|
|
||||||
|
```ini
|
||||||
|
[SAP]
|
||||||
|
host = http://sap.example.com:8000
|
||||||
|
client = 100
|
||||||
|
user = YOUR_USERNAME
|
||||||
|
password = YOUR_PASSWORD
|
||||||
|
```
|
||||||
|
|
||||||
|
### 环境变量配置（可选）
|
||||||
|
|
||||||
|
环境变量优先级高于配置文件：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
export SAP_HOST=http://sap.example.com:8000
|
||||||
|
export SAP_CLIENT=100
|
||||||
|
export SAP_USER=YOUR_USERNAME
|
||||||
|
export SAP_PASSWORD=YOUR_PASSWORD
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ✅ 验证安装
|
||||||
|
|
||||||
|
### 完整验证
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 运行验证脚本
|
||||||
|
python scripts/setup.py verify
|
||||||
|
```
|
||||||
|
|
||||||
|
### 手动验证
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. 验证包导入
|
||||||
|
cd assets
|
||||||
|
python -c "from sapcli import __version__; print(f'sap-cli v{__version__}')"
|
||||||
|
|
||||||
|
# 2. 验证 CLI 入口
|
||||||
|
python main.py --help
|
||||||
|
|
||||||
|
# 3. 验证 SAP 连接
|
||||||
|
python main.py config show
|
||||||
|
|
||||||
|
# 4. 测试基础功能
|
||||||
|
python main.py info --name ZTEST --type prog
|
||||||
|
```
|
||||||
|
|
||||||
|
**预期输出**：
|
||||||
|
```
|
||||||
|
✅ 包导入正常
|
||||||
|
✅ CLI 入口正常
|
||||||
|
✅ 配置文件已加载
|
||||||
|
✅ SAP 连接正常
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 升级指南
|
||||||
|
|
||||||
|
### 方式一：Git 拉取升级
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. 进入项目目录
|
||||||
|
cd ~/AppData/Local/hermes/skills/productivity/sap-cli
|
||||||
|
|
||||||
|
# 2. 拉取最新代码
|
||||||
|
git pull origin main
|
||||||
|
|
||||||
|
# 3. 重新运行安装脚本
|
||||||
|
python scripts/setup.py install
|
||||||
|
|
||||||
|
# 4. 验证升级
|
||||||
|
python scripts/setup.py verify
|
||||||
|
```
|
||||||
|
|
||||||
|
### 方式二：重新克隆升级
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. 备份现有配置
|
||||||
|
cp ~/AppData/Local/hermes/skills/productivity/sap-cli/assets/config.ini ~/config.ini.backup
|
||||||
|
|
||||||
|
# 2. 删除旧目录
|
||||||
|
rm -rf ~/AppData/Local/hermes/skills/productivity/sap-cli
|
||||||
|
|
||||||
|
# 3. 重新克隆
|
||||||
|
git clone https://gitee.com/markwury168/sap-cli-skill.git ~/AppData/Local/hermes/skills/productivity/sap-cli
|
||||||
|
|
||||||
|
# 4. 恢复配置
|
||||||
|
cp ~/config.ini.backup ~/AppData/Local/hermes/skills/productivity/sap-cli/assets/config.ini
|
||||||
|
|
||||||
|
# 5. 验证安装
|
||||||
|
cd ~/AppData/Local/hermes/skills/productivity/sap-cli
|
||||||
|
python scripts/setup.py verify
|
||||||
|
```
|
||||||
|
|
||||||
|
### 检查版本
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 查看当前版本
|
||||||
|
cat VERSION
|
||||||
|
|
||||||
|
# 或通过 CLI 查看
|
||||||
|
cd assets
|
||||||
|
python -c "from sapcli import __version__; print(__version__)"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔍 故障排除
|
||||||
|
|
||||||
|
### 问题1：Python 版本不兼容
|
||||||
|
|
||||||
|
**错误信息**：
|
||||||
|
```
|
||||||
|
❌ Python 3.10+ required, got 3.9.x
|
||||||
|
```
|
||||||
|
|
||||||
|
**解决方案**：
|
||||||
|
```bash
|
||||||
|
# 检查 Python 版本
|
||||||
|
python --version
|
||||||
|
|
||||||
|
# 升级 Python（使用 pyenv）
|
||||||
|
pyenv install 3.11.0
|
||||||
|
pyenv global 3.11.0
|
||||||
|
```
|
||||||
|
|
||||||
|
### 问题2：pip 不可用
|
||||||
|
|
||||||
|
**错误信息**：
|
||||||
|
```
|
||||||
|
⚠️ pip not available, skipping dependency install.
|
||||||
|
```
|
||||||
|
|
||||||
|
**解决方案**：
|
||||||
|
```bash
|
||||||
|
# 确保 pip 可用
|
||||||
|
python -m pip --version
|
||||||
|
|
||||||
|
# 手动安装依赖
|
||||||
|
pip install requests>=2.28.0
|
||||||
|
```
|
||||||
|
|
||||||
|
### 问题3：SAP 连接失败
|
||||||
|
|
||||||
|
**错误信息**：
|
||||||
|
```
|
||||||
|
⚠️ 连接测试失败，请检查配置。
|
||||||
|
```
|
||||||
|
|
||||||
|
**解决方案**：
|
||||||
|
```bash
|
||||||
|
# 1. 检查配置文件
|
||||||
|
cat assets/config.ini
|
||||||
|
|
||||||
|
# 2. 检查网络连接
|
||||||
|
ping sap.example.com
|
||||||
|
|
||||||
|
# 3. 测试 SAP ADT 端点
|
||||||
|
curl http://sap.example.com:8000/sap/bc/adt
|
||||||
|
|
||||||
|
# 4. 检查防火墙和代理设置
|
||||||
|
```
|
||||||
|
|
||||||
|
### 问题4：包导入失败
|
||||||
|
|
||||||
|
**错误信息**：
|
||||||
|
```
|
||||||
|
❌ sapcli package import failed.
|
||||||
|
```
|
||||||
|
|
||||||
|
**解决方案**：
|
||||||
|
```bash
|
||||||
|
# 1. 检查 assets 目录结构
|
||||||
|
ls -la assets/
|
||||||
|
|
||||||
|
# 2. 确保在正确的目录
|
||||||
|
cd assets
|
||||||
|
python -c "import sys; print(sys.path)"
|
||||||
|
|
||||||
|
# 3. 重新安装依赖
|
||||||
|
pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
### 问题5：权限问题（Linux/macOS）
|
||||||
|
|
||||||
|
**错误信息**：
|
||||||
|
```
|
||||||
|
Permission denied: 'setup.py'
|
||||||
|
```
|
||||||
|
|
||||||
|
**解决方案**：
|
||||||
|
```bash
|
||||||
|
# 添加执行权限
|
||||||
|
chmod +x scripts/setup.py
|
||||||
|
|
||||||
|
# 或使用 python 运行
|
||||||
|
python scripts/setup.py all
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📞 获取帮助
|
||||||
|
|
||||||
|
### 查看帮助信息
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 查看安装脚本帮助
|
||||||
|
python scripts/setup.py
|
||||||
|
|
||||||
|
# 查看 CLI 帮助
|
||||||
|
cd assets
|
||||||
|
python main.py --help
|
||||||
|
|
||||||
|
# 查看具体命令帮助
|
||||||
|
python main.py <command> --help
|
||||||
|
```
|
||||||
|
|
||||||
|
### 常用命令示例
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 查看 SAP 系统信息
|
||||||
|
python main.py config show
|
||||||
|
|
||||||
|
# 获取对象信息
|
||||||
|
python main.py info --name ZMY_PROGRAM --type prog
|
||||||
|
|
||||||
|
# 列出对象
|
||||||
|
python main.py list --prefix Z --type prog
|
||||||
|
|
||||||
|
# 下载源码
|
||||||
|
python main.py download --name ZMY_PROGRAM --type prog --output /tmp/
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📚 相关文档
|
||||||
|
|
||||||
|
- [README.md](README.md) - 项目概述和快速开始
|
||||||
|
- [SKILL.md](SKILL.md) - AI Agent 使用指南
|
||||||
|
- [references/](references/) - 详细技术文档
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 更新日志
|
||||||
|
|
||||||
|
### v2.2.1 (当前版本)
|
||||||
|
- 优化安装脚本交互体验
|
||||||
|
- 增强错误处理和日志输出
|
||||||
|
- 支持环境变量配置
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**最后更新**: 2026年7月17日
|
||||||
|
**维护者**: SwiftCode Creative Technology
|
||||||
@@ -1,51 +1,62 @@
|
|||||||
# SAP-CLI-SKILL
|
# SAP-CLI-SKILL
|
||||||
|
|
||||||
sap-cli 的 AI Agent 可分发技能包。封装 SAP ADT REST API，让 AI 助手（Hermes / Claude Code）在终端完成 ABAP 开发对象的完整生命周期管理。
|
## 🎯 项目价值
|
||||||
|
|
||||||
## 与 sap-cli 的关系
|
SAP-CLI-SKILL 是一个让 AI 助手直接操作 SAP ABAP 系统的工具包。
|
||||||
|
|
||||||
| | sap-cli | SAP-CLI-SKILL |
|
**核心价值**：
|
||||||
|---|---|---|
|
- **AI 驱动的 SAP 开发**：AI 助手可以读取、分析、修改 ABAP 代码
|
||||||
| 定位 | 源码开发仓库 | AI Agent 分发包 |
|
- **代码质量自动化**：自动化审计 ABAP 代码，发现潜在问题
|
||||||
| 地址 | [gitee.com/markwury168/sap-cli](https://gitee.com/markwury168/sap-cli) | 本仓库 |
|
- **开发效率提升**：AI 帮助完成重复性开发任务
|
||||||
| 内容 | 完整源码 + 测试 + OpenSpec | 构建产物 + SKILL.md + 安装脚本 |
|
- **持续集成支持**：集成到 CI/CD 流程，实现代码质量门禁
|
||||||
|
|
||||||
源码在 `sap-cli` 修改后，通过 `python scripts/pack_skill.py` 自动构建到本仓库。
|
**适用场景**：
|
||||||
|
- SAP ABAP 代码审计和质量检查
|
||||||
|
- 批量对象处理和转换
|
||||||
|
- AI 辅助开发和重构
|
||||||
|
- 自动化测试和代码审查
|
||||||
|
|
||||||
## 安装
|
---
|
||||||
|
|
||||||
### Hermes Agent
|
## 🚀 快速启动
|
||||||
|
|
||||||
|
### 一键安装
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://gitee.com/markwury168/sap-cli-skill.git ~/AppData/Local/hermes/skills/productivity/sap-cli
|
请帮我安装 sap-cli-skill: https://gitee.com/markwury168/sap-cli-skill/blob/master/INSTALL.md
|
||||||
python ~/AppData/Local/hermes/skills/productivity/sap-cli/scripts/setup.py all
|
|
||||||
```
|
```
|
||||||
|
复制给你的 Agent，几分钟后它就安装好了。
|
||||||
|
|
||||||
### Claude Code
|
### 验证安装
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://gitee.com/markwury168/sap-cli-skill.git ~/.claude/skills/sap-cli
|
cd ~/AppData/Local/hermes/skills/productivity/sap-cli/assets
|
||||||
python ~/.claude/skills/sap-cli/scripts/setup.py all
|
python main.py --help
|
||||||
|
python main.py config show
|
||||||
```
|
```
|
||||||
|
|
||||||
验证：
|
### 快速使用
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd <SKILL_DIR>/assets && python main.py --help
|
# 获取对象信息
|
||||||
|
python main.py info --name ZMY_CLASS --type class
|
||||||
|
|
||||||
|
# 下载源码
|
||||||
|
python main.py download --name ZMY_PROGRAM --type prog --output /tmp/
|
||||||
|
|
||||||
|
# 列出对象
|
||||||
|
python main.py list --prefix Z --type prog
|
||||||
```
|
```
|
||||||
|
|
||||||
## 目录结构
|
---
|
||||||
|
|
||||||
```
|
## 📚 详细文档
|
||||||
SAP-CLI-SKILL/
|
|
||||||
├── SKILL.md # AI Agent 入口（命令速查、工作流、使用约束）
|
|
||||||
├── VERSION # 当前版本号
|
|
||||||
├── assets/ # sap-cli 可执行文件（源码包 + main.py + 配置模板）
|
|
||||||
├── references/ # 详细规则（ADT 约束、错误处理）
|
|
||||||
└── scripts/
|
|
||||||
└── setup.py # 一键安装（依赖 + pip install + 配置）
|
|
||||||
```
|
|
||||||
|
|
||||||
## License
|
- **[INSTALL.md](INSTALL.md)** - 完整安装指南
|
||||||
|
- **[SKILL.md](SKILL.md)** - AI Agent 使用指南
|
||||||
|
- **[references/](references/)** - 技术文档
|
||||||
|
|
||||||
MIT
|
---
|
||||||
|
|
||||||
|
**当前版本**: 2.2.1
|
||||||
|
**维护者**: SwiftCode Creative Technology
|
||||||
Reference in New Issue
Block a user