吴让宇
c5905a5b1e
方向反转：此前 SKILL.md 是「模板渲染产物」、sap-cli 是源；现 sap-cli 归档， sap-cli-skill 承接开发与分发，SKILL.md 回归手工维护的正本。 迁移（来自 sap-cli，共 104 文件）： - tests/ 692 例测试（15 个文件的内联 sys.path 改指 assets/） - openspec/ SDD 规格与归档变更（42 文件） - docs/ 开发文档与 ADT 原理（含 dev/CLAUDE.md、AGENTS.md） - .claude/ rules 副本 + settings.json（供 Claude Code） - .github/ .hermes/ .pre-commit-config.yaml .editorconfig CLAUDE.md - scripts/ 保持仅 setup.py（pack_skill.py 已随旧仓归档，不迁） 修复（迁移暴露的真实缺陷）： - assets/pyproject.toml 的 build-backend 写作 `setuptools.backends._legacy:_Backend`， 该模块在 setuptools 中不存在 → `pip install -e` 从来装不上。改为 build_meta。 实测：临时 venv 安装成功，sap-cli --help 正常列出 31 个命令 - pyproject readme 指向不存在的 assets/README.md（editable 安装会失败）→ 改内联文本 - pyproject urls 改指 sap-cli-skill 机制调整： - .github/workflows/ci.yml 适配 assets/ 布局；顶部注明该工作流仅 GitHub 执行， 本仓在 Gitee 不会自动跑 - pre-commit 增本地测试门禁（Gitee 上真正生效的那道） - .gitignore 合并旧仓完整规则（保留 log/ 下 md 知识库入库，只忽略运行日志） - 大文件上限 100KB→1MB（架构图 512KB） 守卫测试 tests/unit/test_repo_guards.py（10 → 18 例）： - SKILL.md 须记录 parser 全部 CLI 命令 / 铁律 1-5 须为真实小节标题 / 示例不得违反铁律 5 - references/ 规则齐备；.claude/rules 与 references 必须一致（实测抓到一次真实漂移） - VERSION == sapcli.__version__ == README 版本 - 仓内不得再出现 pack_skill.py / skill-src（防废弃流程回潮） 698 tests OK；editable 安装与 CLI 入口经临时 venv 实测通过。 docs/RELEASING.md 重写为单源开发流程。
181 lines
7.6 KiB
Markdown
181 lines
7.6 KiB
Markdown
# sap-cli — AI 协作指南
|
||
|
||
> [!danger] 核心约束：文档优先，禁止擅自读取源代码
|
||
> 本项目提供了完整的技术文档体系，AI 在协作时**必须优先阅读文档**获取所需信息，**严禁未经许可直接读取 Python 源代码文件**（`sapcli/` 包内的 `.py` 文件、`main.py`、`test/` 目录）。
|
||
>
|
||
> 如果发现文档描述与实际行为不一致，**必须先向用户说明差异并征得同意**，才能读取源代码进行校验。
|
||
|
||
## 项目简介
|
||
|
||
sap-cli 是一个命令行工具，通过 SAP ADT REST API 实现 ABAP 开发对象的远程管理（创建、同步、下载、查询、删除），让开发者可以在本地编辑器中编写 ABAP 代码，一行命令同步到 SAP 系统。
|
||
|
||
## 文档体系（AI 必读）
|
||
|
||
> [!important] 文档覆盖了项目的全部设计细节，AI 应按需查阅以下文档，而非阅读源代码。
|
||
|
||
| 文档 | 用途 | 文件路径 |
|
||
| 文档 | 说明 | 路径 |
|
||
|------|------|------|
|
||
| 使用指南 | 命令详解、参数说明、输出示例 | `docs/guide.md` |
|
||
| 技术说明 | 架构、模块职责、通信流程、异常体系 | `docs/dev/architecture.md` |
|
||
| 批量同步设计 | manifest 清单、拓扑排序、批量 sync | `docs/dev/batch-design.md` |
|
||
| 测试报告 | 测试场景覆盖 | `docs/dev/test-report.md` |
|
||
| ADT 学习笔记总览 | ADT 原理系列索引 | `docs/adt/README.md` |
|
||
|
||
### 按需求查阅
|
||
|
||
| 需求 | 文档 |
|
||
|------|------|
|
||
| 了解某个命令怎么用 | `docs/guide.md` |
|
||
| 了解模块接口 / API 调用链 | `docs/dev/architecture.md` |
|
||
| 了解批量同步 / manifest | `docs/dev/batch-design.md` |
|
||
| 了解 ADT REST API 原理 | `docs/adt/` 目录下的系列笔记 |
|
||
| 了解支持哪些对象类型 | `README.md` 功能矩阵 |
|
||
|
||
## AI 行为规范
|
||
|
||
### 1. 文档优先原则
|
||
|
||
- **所有问题先查文档** — 项目文档完整覆盖了架构、命令、API、模块接口、异常体系等全部信息
|
||
- **文档即真相** — 以文档描述为准进行操作，不需要通过读代码"验证"
|
||
- **引用文档回答** — 回答用户问题时引用具体文档路径，方便用户追溯
|
||
|
||
### 2. 源代码访问限制
|
||
|
||
> [!warning] 以下文件属于源代码，未经用户许可**禁止读取**：
|
||
> - `main.py` — CLI 入口
|
||
> - `sapcli/*.py` — 核心包（config / types / client / commands / exceptions / manifest / scanner / sorter）
|
||
> - `test/**/*.py` — 测试套件
|
||
|
||
**允许读取的文件：**
|
||
- `*.md` — 所有文档文件
|
||
- `*.abap` — ABAP 源代码文件（这是用户要同步到 SAP 的业务代码）
|
||
- `config.ini` — 连接配置（注意不要泄露密码）
|
||
- `manifest.json` — 项目清单文件
|
||
- `*.drawio` / `*.png` — 架构图等资源文件
|
||
|
||
### 3. 源代码校验流程
|
||
|
||
当文档描述与实际执行效果不一致时：
|
||
|
||
```
|
||
1. 向用户报告："文档描述 XXX，但实际表现为 YYY，差异点为 ZZZ"
|
||
2. 说明需要读取哪些源文件、读取目的是什么
|
||
3. 等待用户明确同意后，方可读取源代码
|
||
4. 读取后只关注差异点，不要全量阅读无关代码
|
||
```
|
||
|
||
### 4. 典型操作流程
|
||
|
||
#### 帮助用户同步代码到 SAP
|
||
|
||
```
|
||
1. 确认用户的 ABAP 文件路径和对象信息（名称、类型）
|
||
2. 执行: python main.py sync --name <名称> --type <类型> --path <文件路径>
|
||
3. 如果成功 → 告知用户
|
||
4. 如果语法检查失败 → 展示错误信息，提示用户修改后重试
|
||
5. 如果激活失败 → 展示错误信息，提示用户修改后重试
|
||
```
|
||
|
||
#### 帮助用户创建新对象
|
||
|
||
```
|
||
1. 确认对象名称、类型、描述
|
||
2. 执行: python main.py create --name <名称> --type <类型> --description "<描述>"
|
||
3. 创建成功后提示用户下载模板或直接编辑
|
||
```
|
||
|
||
#### 帮助用户批量同步
|
||
|
||
```
|
||
1. 确认项目根目录路径
|
||
2. 如果没有 manifest.json，先执行: python main.py init --path <项目目录>
|
||
3. 预览执行计划: python main.py sync --all --path <项目目录> --dry-run
|
||
4. 确认后执行（推荐指定 --corr_nr 避免交互中断）:
|
||
python main.py sync --all --path <项目目录> --corr_nr <传输请求号>
|
||
5. 如果不指定 --corr_nr，会在启动时弹出一次传输请求选择，后续自动复用
|
||
```
|
||
|
||
## 命令速查
|
||
|
||
```bash
|
||
# 单对象操作
|
||
python main.py create --name <名称> --type <类型> [--description <描述>] [--corr_nr <请求号>]
|
||
python main.py info --name <名称> --type <类型>
|
||
python main.py download --name <名称> --type <类型> --path <保存目录>
|
||
python main.py sync --name <名称> --type <类型> --path <.abap文件> [--corr_nr <请求号>]
|
||
python main.py delete --name <名称> --type <类型>
|
||
|
||
# 批量操作（基于 manifest 清单）
|
||
python main.py init --path <项目目录>
|
||
python main.py sync --all --path <项目目录> [--dry-run] [--fail-fast]
|
||
python main.py refresh --path <项目目录>
|
||
|
||
# 搜索与浏览
|
||
python main.py list --type <类型> [--package <包名>] [--prefix <前缀>]
|
||
python main.py whereused --name <名称> --type <类型>
|
||
python main.py search --query <关键词> [--type <类型>]
|
||
|
||
# 传输管理
|
||
python main.py transport list
|
||
python main.py transport info --corr_nr <请求号>
|
||
python main.py transport release --corr_nr <请求号>
|
||
python main.py transport objects --corr_nr <请求号>
|
||
|
||
# 代码质量
|
||
python main.py check --name <名称> --type <类型>
|
||
python main.py format --name <名称> --type <类型>
|
||
python main.py diff --name <名称> --type <类型> [--path <本地文件>]
|
||
|
||
# 包管理
|
||
python main.py package create --name <包名> [--description <描述>]
|
||
python main.py package info --name <包名>
|
||
python main.py package list --name <包名>
|
||
|
||
# CDS View
|
||
python main.py cds download --name <CDS名> --path <目录>
|
||
python main.py cds sync --name <CDS名> --path <DDL文件>
|
||
python main.py cds create --name <CDS名> [--description <描述>]
|
||
|
||
# 辅助工具
|
||
python main.py analyze --path <项目目录>
|
||
python main.py scaffold --name <名称> --template <模板> [--package <包名>]
|
||
python main.py config show
|
||
python main.py config list-profiles
|
||
```
|
||
|
||
## 对象类型速查
|
||
|
||
| 类型参数 | 说明 | 名称格式 |
|
||
|---------|------|---------|
|
||
| `report` | 程序/报表 | 直接使用程序名 |
|
||
| `class` | ABAP 类 | 直接使用类名 |
|
||
| `interface` | ABAP 接口 | 直接使用接口名 |
|
||
| `function` | 函数模块 | `函数组名/函数模块名` |
|
||
| `functiongroup` | 函数组 | 直接使用函数组名 |
|
||
| `include` | Include 程序 | 直接使用程序名 |
|
||
| `domain` | 域 | 直接使用域名 |
|
||
| `dataelement` | 数据元素 | 直接使用元素名 |
|
||
| `table` | 透明表 | 直接使用表名 |
|
||
| `structure` | 结构 | 直接使用结构名 |
|
||
| `tabletype` | 表类型 | 直接使用类型名 |
|
||
| `cdsview` | CDS View | 直接使用 CDS 名 |
|
||
| `messageclass` | 消息类 | 直接使用消息类名 |
|
||
| `view` | 数据库视图 | 直接使用视图名 |
|
||
| `searchhelp` | 搜索帮助 | 直接使用搜索帮助名 |
|
||
| `lockobject` | 锁对象 | 直接使用锁对象名 |
|
||
|
||
## 依赖排序优先级（批量同步）
|
||
|
||
```
|
||
domain(10) → dataelement(20) → structure(25) → table(30) → tabletype(40) → view(42) → lockobject(44) → searchhelp(46) → messageclass(48) → interface(50) → class(60) → function(70) → functiongroup(75) → include(78) → cdsview(79) → report(80)
|
||
```
|
||
|
||
## 关键技术要点
|
||
|
||
- **认证**: HTTP Basic Auth + CSRF Token
|
||
- **sync 流程**: 检查/创建 → 锁定 → 写入 → 解锁 → 语法检查 → 激活
|
||
- **锁定机制**: stateful session，自动检测传输请求绑定
|
||
- **配置加载优先级**: 环境变量 > --config 指定文件 > 工作目录 config.ini > 脚本目录 config.ini
|
||
- **唯一第三方依赖**: `requests`
|