refactor: 本仓升为唯一源（原 sap-cli 源码仓归档）

方向反转：此前 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 重写为单源开发流程。
2026-09-11 00:40:15 +08:00
parent e786742bcb
commit c5905a5b1e
104 changed files with 20744 additions and 10 deletions
@@ -0,0 +1,180 @@
+# 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`