# 金蝶 EAS/sHR 对接 Skills 使用说明

本压缩包包含两个 Agent Skill（`SKILL.md` 标准目录），可用于 **Cursor** 与 **Claude Code**，指导 AI 在金蝶 EAS/sHR 上做 **单点登录（SSO）** 与 **待办/待阅推送**。

| 目录 | Skill 名 | 用途 |
|------|----------|------|
| `kdshrsso/` | **kdshrsso** | 单点登录：泛微 E10 / 钉钉 / IDM / Azure 等对接 sHR |
| `kdshrpmsg/` | **kdshrpmsg** | 待办、待阅推送：泛微统一待办 / 门户 PORTAL-* 等 |

两者常一起用：待办深链要能登录，入口须与 SSO 一致。  
**同一套文件夹内容**可分别拷到 Cursor 或 Claude Code 的 skills 目录（路径不同，见下）。

---

## 一、安装（解压后）

两套工具的目录名都叫 `skills/`，但父目录不同，**不要混放**。

### 1.1 Cursor

| 范围 | Windows | macOS / Linux |
|------|---------|----------------|
| 个人全局 | `C:\Users\<用户名>\.cursor\skills\` | `~/.cursor/skills/` |
| 仅本项目 | `<项目>\.cursor\skills\` | `<项目>/.cursor/skills/` |

注意：不要放到 `.cursor/skills-cursor/`（Cursor 内置技能目录）。

### 1.2 Claude Code

| 范围 | Windows | macOS / Linux |
|------|---------|----------------|
| 个人全局 | `C:\Users\<用户名>\.claude\skills\` | `~/.claude/skills/` |
| 仅本项目（推荐团队共享） | `<项目>\.claude\skills\` | `<项目>/.claude/skills/` |

官方说明：[Extend Claude with skills](https://code.claude.com/docs/en/skills)

### 1.3 解压后的目录结构（两种工具相同）

```
skills/                    ← 上面表里对应的 .cursor 或 .claude 下的 skills
├── kdshrsso/
│   ├── SKILL.md           ← 必需
│   └── *.md               ← 参考文档，随目录一起拷贝
└── kdshrpmsg/
    ├── SKILL.md
    └── *.md
```

同时用 Cursor 和 Claude Code 时：把 `kdshrsso`、`kdshrpmsg` **各拷一份**到 `.cursor/skills/` 与 `.claude/skills/`，或项目内两套路径各放一份。

### 1.4 注意

- **必须保留文件夹结构**（目录名 = 技能名），不要只拷贝单个 `SKILL.md` 改名。
- Cursor：安装后重启 Cursor / 重新打开项目。
- Claude Code：拷到已有 skills 目录后，一般当前会话会很快生效；若是新建了顶层 `skills` 目录，需 **重启一次 Claude Code**。
- 项目技能进 Git 时：Cursor 用 `.cursor/skills/`，Claude Code 用 `.claude/skills/`；团队若两边都用，可两个目录都提交（内容相同）。

---

## 二、在 Cursor 里怎么用

在 Agent / Chat 中**点名技能**或描述业务即可，例如：

**SSO：**

- 「按 **kdshrsso**，给新项目接泛微 E10 SSO」
- 「按报业 / BaoYPro 的 B-qy 模式做单点」
- 「退出后又自动登录了，按 kdshrsso 查联邦退出」

**待办：**

- 「按 **kdshrpmsg**，对接泛微统一待办」
- 「按报业 weaverTodo 推送待办，深链走 SSO」
- 「只要待办推送，SSO 已做好」

**上线：**

- 「按 skill 做 **切生产 / 上线**」

Agent 应按 skill 要求：**先提问确认（intake），再写代码**；说「上线」时先列待改配置、确认生产地址，再改文件。

---

## 三、在 Claude Code 里怎么用

本包格式与 Claude Code Skills 兼容（目录 + `SKILL.md` + 同级参考文档）。安装到 `~/.claude/skills/` 或项目 `.claude/skills/` 后即可。

### 3.1 推荐：斜杠命令显式调用

在 Claude Code 输入框输入 `/`，应能看到（目录名即命令名）：

- `/kdshrsso` — 加载 SSO 技能  
- `/kdshrpmsg` — 加载待办/待阅技能  

示例：

```
/kdshrsso
按 B-qy 对接泛微 E10，测试 SHR 地址是 ……，请先做 intake 提问。
```

```
/kdshrpmsg
对接泛微统一待办，深链走 /qy/auth/weaver/app.do，请先确认渠道与配置文件名。
```

两个都要时，可先 `/kdshrsso` 再 `/kdshrpmsg`，或开场说明「先 SSO 后待办，两个 skill 一起按」。

### 3.2 也可自然语言触发

不打 `/` 时，若描述命中 skill 的 `description`（如「金蝶 SSO」「泛微待办」「weaverTodo」），Claude 可能自动加载。重要流程建议仍用 **`/kdshrsso` / `/kdshrpmsg`**，避免漏载。

### 3.3 行为约定（与 Cursor 相同）

- 新项目 / 新 IdP：须先做 **intake 提问**，确认后再改代码。  
- 用户说「上线 / 切生产」：先列待改文件与生产 URL，确认后再改。  
- 同目录下的 `weaver-oauth-qywar-reference.md` 等参考文档，Claude 会在需要时按 `SKILL.md` 指引读取，请勿删掉。

### 3.4 Claude Code 侧常见问题

| 现象 | 处理 |
|------|------|
| 输入 `/` 看不到 kdshrsso | 确认路径是 `.claude/skills/kdshrsso/SKILL.md`（不是 `.cursor/...`）；重启 Claude Code |
| 只有个人机生效、云端/同事没有 | 把技能放进项目 `.claude/skills/` 并提交 Git（云端会话不读你本机 `~/.claude/skills/`） |
| 想限制只能手动触发 | 可在 `SKILL.md` 的 YAML 里加 `disable-model-invocation: true`（加后需用 `/技能名` 才会加载） |

---

## 四、选型速查

### kdshrsso — SSO 模式

| 模式 | 适用 | 典型入口 |
|------|------|----------|
| **A** Filter 覆盖 | Azure / 标准 OIDC，希望全站 `/shr` 自动鉴权 | `/shr?adsso` 等 |
| **B** Servlet + Ltpa | 企业 IDM、OAToSHR 深链 | `/shr/api/oAToSHR` |
| **B-qy** qy.war + index2sso | **泛微 E10 / 钉钉**（报业类） | `/qy/auth/weaver/app.do` |

不确定时让 Agent 按 skill 里的 Quick decision 推荐，再由你确认。

### kdshrpmsg — 消息推送

| 场景 | 是否适合 |
|------|----------|
| 流程待办推到门户 / 泛微统一待办 | 适合 |
| BMC 待阅 / 通知 | 适合 |
| 玉湖式 PORTAL-* + ESB | 适合（见包内 yhpro / portal 参考） |
| 只做钉钉/飞书、无门户 | 部分：单独渠道 + 独立配置文件 |
| 替换产品消息中心整套 | 不适合 |

---

## 五、开工前 Agent 会问什么（请提前准备）

### SSO（kdshrsso）

1. IdP 类型（泛微 / 钉钉 / 飞书 / IDM / Azure…）及接口文档  
2. 模式 A / B / B-qy  
3. sHR 地址（协议+主机+端口）、是否 Apusic、能否部署 `qy.war`  
4. 人员映射（IdP 字段 ↔ sHR 工号/自定义字段等）  
5. 回调 URL（通常无 `.do`）  
6. 是否改门户 `login_withForm.js`；本地 `/shr/home.do` 是否保留  
7. 是否要联邦退出；IdP 退出重定向白名单  

### 待办（kdshrpmsg）

1. 渠道与接口文档  
2. 只要待办，还是待办+待阅；SSO 是否同期做  
3. 鉴权方式与配置文件名（勿混渠道）  
4. 接收人字段（工号/手机/userid）  
5. 幂等键规则  
6. 深链 SSO 入口（须与 kdshrsso 一致）  
7. 新建独立 Dao，还是多渠道 Router  

你说「按报业 / 按 BaoYPro」时，Agent 可按默认假设复述一次，你确认后再改代码。

---

## 六、压缩包内容清单

### kdshrsso/

| 文件 | 说明 |
|------|------|
| `SKILL.md` | 主流程：intake、模式选型、切生产、排错要点 |
| `weaver-oauth-qywar-reference.md` | 泛微 E10 / qy.war（B-qy）详细参考 |
| `portal-login-reference.md` | 门户 eassso / login_withForm |
| `idm-servlet-reference.md` | Option B（OAToSHR） |
| `idm-filter-reference.md` | Option A（IDM Filter） |
| `azure-oauth-reference.md` | Azure / OIDC Filter |
| `migration-guide.md` | 迁移注意 |

### kdshrpmsg/

| 文件 | 说明 |
|------|------|
| `SKILL.md` | 主流程：intake、SPI、切生产、与 SSO 协同 |
| `weaver-baoy-plan.md` | 报业 / 泛微统一待办落地计划与约定 |
| `weaver-receive-todo-api.md` | 泛微 ReceiveTodo / OpenAPI 说明 |
| `yhpro-reference.md` | 玉湖门户待办参考实现 |
| `portal-api-map.md` | PORTAL-* 接口对照 |

---

## 七、使用建议与注意事项

1. **密钥与生产地址不要写进 skill、不要提交 Git**；只放服务器 properties / 本地私有配置。  
2. SSO 与待办同期交付时，**先定深链入口**（如 `/qy/auth/weaver/app.do`），两边保持一致。  
3. 桌面进 sHR 优先 **HTML POST `index2sso`**，避免 LTPA 放进 Location 导致多重编码。  
4. PC 待办深链用**显式平台路径**（`/qy/auth/weaver/...`），不要依赖仅靠 UA 的 Unified `/auth/app`。  
5. Skill 内若出现示例主机、路径，请改成你们环境；报业项目还可对照仓库内 `docs/integration/*.html`（若有）。  
6. 说「上线 / 切生产」时，Agent 应先列文件清单并确认生产 URL，再改配置。

---

## 八、推荐对话开场白（可复制）

### Cursor

```
请加载 kdshrsso 和 kdshrpmsg。
我们要对接：泛微 E10（或钉钉/飞书/IDM）。
环境：测试 SHR 地址是 ……；是否有 qy.war：……
人员映射：……
请先按 skill 做 intake 提问，确认后再写代码。不要直接改生产配置。
```

### Claude Code

```
/kdshrsso
我们要对接：泛微 E10（或钉钉/飞书/IDM）。
环境：测试 SHR 地址是 ……；是否有 qy.war：……
人员映射：……
请先做 intake 提问，确认后再写代码。不要直接改生产配置。
```

需要待办时再执行：

```
/kdshrpmsg
深链 SSO 入口与上面一致；请先确认渠道、配置文件名与人员字段。
```

### 切生产（两种工具通用）

Cursor 可直接说；Claude Code 建议先 `/kdshrsso`（及需要时 `/kdshrpmsg`）再发：

```
按 kdshrsso / kdshrpmsg 做切生产。
生产 SHR：……
生产 ecology / OpenAPI：……
请先列出要改的文件和项，我确认后再改。
```

---

## 九、版本与反馈

- 适用产品：金蝶 EAS / sHR（含 Apusic 等常见部署）  
- 适用工具：**Cursor**、**Claude Code**（同一套 `kdshrsso` / `kdshrpmsg` 目录）  
- 参考落地：YHPro（门户 PORTAL）、BaoYPro（泛微 B-qy + 统一待办）  
- 问题反馈：把对话中 Agent 的 intake 结论与报错日志一并反馈给技能维护人，便于更新 `SKILL.md` / 参考文档  

**Cursor**：对话中点名 **kdshrsso** / **kdshrpmsg**。  
**Claude Code**：输入 **`/kdshrsso`** / **`/kdshrpmsg`**。