# xiaoma-generate-rap-interface（安装说明）

把需求/详设文档里的接口，经 AI 提取 + 人工确认后同步到 RAP 接口管理平台。

这个目录是自包含的：**整个文件夹拷走就能用**，不需要 jiekou-sync 仓库、不需要 MCP server、不需要 `npm install`。

## 安装

### 1. 确认 Node

```bash
node -v    # 需要 v20 或更高
```

没有就装：<https://nodejs.org>（LTS 版即可）。

### 2. 放到 skills 目录

| 放法 | 位置 | 生效范围 |
|------|------|----------|
| 个人（推荐） | `~/.claude/skills/xiaoma-generate-rap-interface/` | 所有项目都能用 |
| 项目 | `<项目>/.claude/skills/xiaoma-generate-rap-interface/` | 只在该项目工作区 |

Windows 上 `~` 是 `C:\Users\<你的用户名>`。

需求文档一般散在各个业务仓库里，所以**建议放个人目录**，否则换个项目就没了。

```bash
# 例：从 U 盘/共享目录拷到个人 skills
mkdir -p ~/.claude/skills
cp -r /path/to/xiaoma-generate-rap-interface ~/.claude/skills/
```

拷完确认结构：

```
xiaoma-generate-rap-interface/
├── SKILL.md             # agent 读的主指令
├── README.md            # 本文件
├── change-detection.md  # 算「本次改了哪些接口」的 git 逻辑
├── code-extraction.md   # 从 Java/Spring 代码提取接口字段的规则
├── reference.md         # 格式与平台行为细节
├── examples.md          # 完整走一遍的例子
└── scripts/
    └── rap.mjs          # RAP CLI，无第三方依赖
```

### 3. 自检

```bash
node ~/.claude/skills/xiaoma-generate-rap-interface/scripts/rap.mjs doctor
```

看三项：`node` ≥ 20、`baseUrlReachable: true`、`scriptPath` 指向你刚拷的位置。

地址不可达就是没连公司网络/VPN，或者你们的 RAP 不在默认地址上（见下）。

### 4. 用

在 Claude Code 里输入 `/xiaoma-generate-rap-interface`，然后描述任务，例如「把 D:\code\xxx 里改的接口同步到 RAP」。

本 skill **仅手动调用**：不会因为你随口提到「同步接口到 RAP」就自动触发，必须由你显式输入 `/xiaoma-generate-rap-interface`（或点名用这个 skill）才会启用。

**新增和更新都从本地代码取材**：优先用工作区未提交的改动（新增接口通常就是那几个未追踪的新文件），没有就让你从**本分支自己的提交**里点名用哪次。需求文档只用来圈范围和补字段说明——文档常滞后于实现，代码才是 RAP 该反映的东西。

### 两道确认门禁

Agent 不会闷头往 RAP 上写，中间有两次必须由你点头：

| 门禁 | 时机 | 回读什么 |
|---|---|---|
| **A** | 登录前 | RAP 地址 / 账号 / 代码仓库 / 开发分支 / 对比分支 / 取材基准，6 项连同默认值一起列出 |
| **B** | 写入前 | 目标仓库模块、将要写入的每一条接口（新增还是更新、路径、字段增删、代码来源） |

两处都要你回复「确认」才继续；你改其中一项，它会把整张卡片重新回读一遍再等你确认。

**只增不删**：这个 skill 只创建和更新接口，不会删除任何 RAP 接口——删接口你自己去页面上做。

## 账号密码怎么处理

- 每次会话由你在对话里提供，**不存任何配置文件**。
- 登录后只有 cookie 落到系统临时目录（`session.json`，权限 0600），约 8 小时有效，期间不会再问密码。
- 不想让密码出现在对话记录里：在输入框用 `!` 前缀自己执行登录命令，agent 只会复用会话。
- 共用电脑用完记得 `node <脚本> logout`。

## 换成你们自己的 RAP 地址

默认 API 地址是 `http://rap.corp.yljr.com:8080`（漏写端口会自动补 `:8080`）。地址不同就在登录时显式传：

```bash
RAP_BASE_URL='http://your-rap.example.com:8080' RAP_USERNAME='<账号>' RAP_PASSWORD='<密码>' \
  node ~/.claude/skills/xiaoma-generate-rap-interface/scripts/rap.mjs login
```

编辑器页地址默认取 API 地址去掉 `:8080`；不一致时另传 `RAP_WEB_BASE_URL`。登录路径默认 `/account/login`，可用 `RAP_LOGIN_PATH` 覆盖。

## 不用 agent，单独当 CLI 使

```bash
node scripts/rap.mjs            # 看所有命令
node scripts/rap.mjs doctor     # 自检
node scripts/rap.mjs repos      # 列仓库
node scripts/rap.mjs repo 123   # 列模块与接口
node scripts/rap.mjs itf 34935  # 接口详情（含入出参）
node scripts/rap.mjs sync plan.json
```

## 排查

| 现象 | 处理 |
|------|------|
| `需要 Node >= 20` | 升级 Node |
| `doctor` 显示 `baseUrlReachable: false` | 连公司网络/VPN；核对地址与端口 |
| 登录失败 | 设 `RAP_LOG_FILE=/tmp/rap.log` 重跑，日志里有完整请求响应（密码已脱敏） |
| Windows cmd 里中文乱码 | 用 Git Bash 或 PowerShell，或先执行 `chcp 65001` |
| Claude Code 里看不到这个 skill | 确认目录名是 `xiaoma-generate-rap-interface` 且 `SKILL.md` 在其根下；重启会话。本 skill 仅手动调用，用 `/xiaoma-generate-rap-interface` 触发 |

更多细节：[SKILL.md](SKILL.md)、[change-detection.md](change-detection.md)、[code-extraction.md](code-extraction.md)、[reference.md](reference.md)、[examples.md](examples.md)。