From c5c6089f89fb63816901893f5b3579332854f567 Mon Sep 17 00:00:00 2001
From: oliver <zhoutianjun127@126.com>
Date: Tue, 8 Sep 2026 23:43:29 +0800
Subject: [PATCH] Document uds-skill-auth in the plugin for easy handoff to
 skill authors.

Add a dedicated doc page and link it from the README and auth standard.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 uds-auth/README.zh.md                   |  8 ++-
 uds-auth/docs/skill-auth-standard.zh.md |  2 +
 uds-auth/docs/uds-skill-auth.zh.md      | 90 +++++++++++++++++++++++++
 3 files changed, 97 insertions(+), 3 deletions(-)
 create mode 100644 uds-auth/docs/uds-skill-auth.zh.md

diff --git a/uds-auth/README.zh.md b/uds-auth/README.zh.md
index 958114a8..fbb7ee06 100644
--- a/uds-auth/README.zh.md
+++ b/uds-auth/README.zh.md
@@ -43,11 +43,13 @@ originSystemCode: ''
 - **默认兜底账号**（扫码不可用时）：用户名 `administrator`，密码 `Admin@123`（首次启动自动启用；可在设置中改密或关闭）
 - **ACL**：租户边界以工作区为准（可见工作区下的会话可访问）；`session-owners.json` 仅记录工号供导出/分析，不是主鉴权键
 
-## Skill 认证
+## Skill 认证（给他人改造 skill 时传这些）
 
-见 [docs/skill-auth-standard.zh.md](docs/skill-auth-standard.zh.md)。
+1. **标准**：[docs/skill-auth-standard.zh.md](docs/skill-auth-standard.zh.md)  
+2. **公共 skill 说明（可直接转发）**：[docs/uds-skill-auth.zh.md](docs/uds-skill-auth.zh.md)  
+3. **公共 skill 目录（可拷贝）**：[../skills/uds-skill-auth](../skills/uds-skill-auth)
 
-**必须安装 skill**：[`skills/uds-skill-auth`](../skills/uds-skill-auth)（认证公共库）。业务 skill 依赖它，而不是插件源码里的 helpers。
+现场顺序：装本插件 → 安装 `uds-skill-auth` → 扫码登录 → 再装业务 skill。
 
 可配置：`retainSkillCredentialsOnLogout`（默认 true）、`skillCredentialTtlSeconds`、`outboundAllowedHosts`。
 
diff --git a/uds-auth/docs/skill-auth-standard.zh.md b/uds-auth/docs/skill-auth-standard.zh.md
index 374ecbaa..d3a52602 100644
--- a/uds-auth/docs/skill-auth-standard.zh.md
+++ b/uds-auth/docs/skill-auth-standard.zh.md
@@ -2,6 +2,8 @@
 
 面向 DeepSeekHarness：现场安装 **uds-auth 插件** + **uds-skill-auth skill** 后，第三方 / 自研 skill 按本标准取凭证或出站调用。
 
+**转发给改造方时**：连同 [uds-skill-auth.zh.md](./uds-skill-auth.zh.md) 与目录 `skills/uds-skill-auth/` 一起给。
+
 ## 现场形态
 
 ```text
diff --git a/uds-auth/docs/uds-skill-auth.zh.md b/uds-auth/docs/uds-skill-auth.zh.md
new file mode 100644
index 00000000..965e424e
--- /dev/null
+++ b/uds-auth/docs/uds-skill-auth.zh.md
@@ -0,0 +1,90 @@
+# uds-skill-auth（给他人传递用）
+
+把**本文 + 同仓库 skill 目录**发给改造方即可。业务 skill 必须依赖本公共 skill，不能只装插件。
+
+## 仓库位置（可直接拷贝整目录）
+
+```text
+skills/uds-skill-auth/
+  SKILL.md
+  scripts/uds_skill_auth.py
+```
+
+现场：拷到对方 `skills/` 下，与业务 skill **同级**。
+
+## 依赖链
+
+```text
+uds-auth 插件（Host）
+  → skill「uds-skill-auth」（公共库，本页）
+  → 用户扫码登录
+  → 业务 skill
+```
+
+完整契约：[skill-auth-standard.zh.md](./skill-auth-standard.zh.md)
+
+## SKILL.md（安装后目录内同名文件）
+
+```markdown
+---
+name: uds-skill-auth
+description: UDS 技能认证公共库。其它依赖 UDS 登录的 skill 必须安装本 skill，通过其 scripts/uds_skill_auth.py 取凭证或出站调用。需现场已安装 uds-auth 插件且用户已扫码登录。
+---
+
+# uds-skill-auth（认证公共 Skill）
+
+本 skill **不是业务能力**，而是给其它 skill 用的公共库。
+
+## 现场依赖
+
+1. 安装并启用 uds-auth 插件
+2. 安装本 skill（uds-skill-auth）到 skills 目录
+3. 用户扫码登录
+4. 再安装/使用业务 skill
+
+## 给其它 Skill 用
+
+业务 skill 的 Python 把本 skill 的 scripts/ 加入 sys.path 后：
+
+from uds_skill_auth import resolve, request, UdsAuthError
+creds = resolve()
+out = request("POST", url, headers={...}, body={...})
+```
+
+## 业务 skill 如何引用（复制这段即可）
+
+```python
+from pathlib import Path
+import sys
+
+def load_uds_skill_auth():
+    here = Path(__file__).resolve().parent
+    # .../skills/<业务>/scripts → .../skills/uds-skill-auth/scripts
+    candidate = here.parents[1] / "uds-skill-auth" / "scripts"
+    if not (candidate / "uds_skill_auth.py").is_file():
+        raise RuntimeError("请先安装 uds-skill-auth skill（与业务 skill 同级）")
+    sys.path.insert(0, str(candidate))
+    import uds_skill_auth
+    return uds_skill_auth
+```
+
+或设置环境变量 `UDS_AUTH_HELPERS` = 本 skill 的 `scripts` 绝对路径。
+
+## API 摘要
+
+| 函数 | 用途 |
+|------|------|
+| `resolve(apply_env_aliases=True)` | 向 Host `POST /uds-auth/agent-credentials` 取 `empNo`+`token`；默认写入进程内 `EMP_NO`/`AUTH_VALUE`/`coclaw_*` |
+| `request(method, url, headers=..., body=...)` | 向 Host `POST /uds-auth/outbound` 出站；Host 注入鉴权头 |
+| `UdsAuthError` | 未登录 / 连不上 Host / 白名单拒绝等 |
+
+Agent 环境（已注入，勿在 SKILL 里教打印密钥）：`DSH_SESSION_ID`、`DSH_WEB_URL`。
+
+## 改造现有 skill 时给 AI 的最短说明
+
+1. 现场已装 uds-auth + 本 skill `uds-skill-auth`  
+2. 删掉读全局 `coclaw_token`/`AUTH_VALUE` 的逻辑  
+3. 用上面的 `load_uds_skill_auth()` + `resolve()` 或 `request()`  
+4. SKILL.md 写明依赖 `uds-skill-auth`，禁止教 printenv token  
+
+实现源码见：`skills/uds-skill-auth/scripts/uds_skill_auth.py`。