Files

T

吴让宇 c5905a5b1e 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

3.5 KiB

Raw Permalink Blame History

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

变更流程

查阅 spec: 在 openspec/specs/ 中找到相关的 domain spec
创建 change: 在 openspec/changes/<name>/ 下创建提案
编写 proposal.md: 描述变更内容、影响范围
编写 design.md: 技术设计，包含 ADT 端点详情
编写 tasks.md: 任务列表，每个任务独立可测试
实现: 按 tasks.md 逐步编写代码
更新 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 对象类型支持：

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

新增 CLI 命令

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

错误处理

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

测试

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 端点，需要大写名称

3.5 KiB Raw Permalink Blame History Unescape Escape