# AGENTS.md — AI 代理协作指南

## 项目概述

sap-cli 是 Python CLI 工具，通过 SAP ADT REST API 管理 ABAP 开发对象。
修改代码前请先阅读 `CLAUDE.md` 了解项目结构和开发规范。

## OpenSpec 规范驱动开发

本项目使用 OpenSpec 进行规范驱动开发。**修改任何功能前，必须先查阅对应的 spec 文件。**

### Spec 文件位置

所有系统行为的 source of truth 位于 `openspec/specs/` 下：

| 域 | 文件 | 内容 |
|----|------|------|
| 连接与认证 | `openspec/specs/connection/spec.md` | 登录、认证、会话管理 |
| 对象生命周期 | `openspec/specs/object-lifecycle/spec.md` | 16 种对象类型的 CRUD |
| 批量操作 | `openspec/specs/batch-ops/spec.md` | 初始化、批量同步、清单刷新 |
| 搜索与浏览 | `openspec/specs/search-browse/spec.md` | 对象列表、where-used、源码搜索 |
| 传输管理 | `openspec/specs/transport/spec.md` | 传输请求管理、传输对象列表 |
| 代码质量 | `openspec/specs/quality/spec.md` | ATC 检查、代码格式化、Diff |
| 配置管理 | `openspec/specs/config/spec.md` | 多系统配置、凭据存储、Profile |

### 变更流程

1. **查阅 spec**: 在 `openspec/specs/` 中找到相关的 domain spec
2. **创建 change**: 在 `openspec/changes/<name>/` 下创建提案
3. **编写 proposal.md**: 描述变更内容、影响范围
4. **编写 design.md**: 技术设计，包含 ADT 端点详情
5. **编写 tasks.md**: 任务列表，每个任务独立可测试
6. **实现**: 按 tasks.md 逐步编写代码
7. **更新 spec**: 完成后将变更合并回 specs/

### Spec 编写规则

- 使用 Given/When/Then 格式编写 Scenario
- 每个 Requirement MUST 指定 ADT API 端点
- 使用 RFC 2119 关键词: SHALL（必须）、MUST（强制）、SHOULD（推荐）
- 中文编写说明文字，英文编写 Requirement 名称和 Scenario 关键词

## 代码修改指南

### 修改前检查清单

- [ ] 阅读了相关的 spec 文件
- [ ] 理解了现有的代码结构
- [ ] 已创建 change proposal（如果涉及功能变更）
- [ ] 了解受影响的 ADT 端点

### 代码风格

- PEP 8 编码规范
- 使用 type hints（`from __future__ import annotations`）
- 使用 f-strings 格式化字符串
- 函数和类使用 docstring
- logging 使用 `logging.getLogger("sapcli.module")`

### 新增对象类型

如需添加新的 ABAP 对象类型支持：

1. 在 `sapcli/types.py` 中定义 `ObjectTypeConfig` 并 `_register()`
2. 更新 `openspec/specs/core/spec.md` 的类型注册表
3. 如有特殊的 URI 模板或创建逻辑，在 `sapcli/client.py` 中处理
4. 在 `sapcli/scanner.py` 的 `DIRECTORY_TYPE_MAP` 中添加目录映射
5. 编写测试用例

### 新增 CLI 命令

1. 在 `sapcli/cli/parser.py` 的 `build_parser()` 中添加 subparser
2. 在 `sapcli/commands/` 下实现 `cmd_xxx()` 函数（或添加到现有模块）
3. 在 `sapcli/commands/__init__.py` 中导出
4. 在 `sapcli/cli/app.py` 的 `command_map` 中注册
5. 更新相关 spec 文件
6. 编写测试用例

### 错误处理

- 所有自定义异常继承自 `SapCliError`
- 新增异常类型在 `sapcli/exceptions.py` 中定义
- CLI 主循环捕获 `SapCliError`，打印友好信息后 exit(1)

## 测试

```bash
python -m pytest tests/test_sapcli.py -v
```

## 注意事项

- SAP ADT REST API 使用 HTTP Basic Auth + CSRF Token
- 大部分 ADT 端点需要 stateful 会话（锁定/写入时）
- DDIC 对象通过 XML body 创建（非纯文本）
- function 类型名称格式: `组名/模块名`
- tabletype 使用 VIT 端点，需要大写名称