吴让宇
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 重写为单源开发流程。
98 lines
3.5 KiB
Markdown
98 lines
3.5 KiB
Markdown
# 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 端点，需要大写名称
|