chore: 开发专用 JWT 密钥、密钥生成脚本与轮换文档

背景：此前全环境共用一把 JWT 密钥（config/jwt/jwt-private.pem）。它相当于
"能冒充 9001/9002/9003 的万能钥匙"（实测边界：签名有效 + 用户存在且启用才通过，
伪造新用户与使用禁用账号都会被拒）。为避免同一把密钥将来又变成生产密钥，
本次引入开发专用密钥，并把签发侧收敛到配置。

改动：
1. 新增 tools/generate_jwt_keys.py：可复现地生成 RS256 密钥对（PKCS#8 / SPKI），
   打印公钥 SHA-256 指纹便于核对服务端加载的是否同一把；密钥已存在时默认拒绝
   覆盖，避免误操作导致所有已签发令牌立即失效。
2. 生成开发专用密钥到 config/jwt/dev/（该目录整体已被 .gitignore 忽略，不入库）。
3. 三个工具脚本不再硬编码私钥路径，改为读配置：acceptance_check 与 demo_agent_e2e
   走 get_settings().jwt_private_key_path，smoke_check 因刻意不依赖 app 包而读
   JWT_PRIVATE_KEY_PATH 环境变量。今后轮换密钥只需改 .env 一处。
4. .env、.env.example 与 Settings 默认值统一指向 config/jwt/dev/。
5. 新增 docs/21-JWT密钥管理与轮换.md：密钥分工（服务端只读公钥，
   JWT_PRIVATE_KEY_PATH 在 app/ 中无任何读取点，故生产机可只挂公钥）、
   克隆后必须自行生成、多人共用一个服务时必须共用同一把私钥、
   轮换的影响面与生产部署要点、安全红线。
6. 记录一处易被忽略的问题：生产环境的 JWT_ISSUER / JWT_AUDIENCE 也应与开发不同，
   否则开发环境签发的令牌在生产上依然有效——这比换密钥更容易漏。

说明：本次提交不含任何密钥文件（.env 与 config/jwt/ 均在 .gitignore 中）。
旧密钥 config/jwt/jwt-private.pem 已退役但保留未删，配置不再引用它，
用它签发的令牌会被拒绝。

验证：ruff 通过、mypy 103 文件无错、unit+contract 447 passed、integration 29 passed、
acceptance_check --production 7 PASS、demo_agent_e2e 9/9 PASS——均使用新密钥完成
签发与验签。

docs/21-JWT密钥管理与轮换.md

@@ -0,0 +1,114 @@
+# JWT 密钥管理与轮换
+
+> 适用对象：底座维护者、接入的业务 Agent 开发者。
+> 相关配置项：`JWT_PRIVATE_KEY_PATH`、`JWT_PUBLIC_KEY_PATH`（`.env`）。
+
+## 1. 现在有几把密钥
+
+| 文件 | 用途 | 状态 |
+| --- | --- | --- |
+| `config/jwt/dev/jwt-private.pem` / `jwt-public.pem` | **开发专用**（服务端验签，脚本签发） | **正在使用** |
+| `config/jwt/jwt-private.pem` / `jwt-public.pem` | 旧密钥（曾是默认） | **已退役**，配置不再指向它，用它签的令牌会被拒绝，可删 |
+| 生产密钥 | 上线时在生产机上生成 | 尚不存在（本就不该在开发机生成） |
+
+开发密钥的公钥指纹可以用生成脚本查看；核对"服务端加载的是不是同一把公钥"时用它比对，
+比对人肉看到的文件内容可靠。
+
+## 2. 密钥不进版本库（这是设计，不是遗漏）
+
+`config/jwt/` 已在 `.gitignore` 里，所以**克隆仓库后是没有密钥的**，服务会直接启动失败：
+
+```
+RuntimeError: JWT public key cannot be read: .../config/jwt/dev/jwt-public.pem
+```
+
+看到这个报错不要去改 `.gitignore`，按下面第 3 节生成即可。
+
+**关键分工（很容易搞反）**：
+
+- **服务端只需要公钥** —— 验签用。`app/core/security.py` 只读 `JWT_PUBLIC_KEY_PATH`，
+  `JWT_PRIVATE_KEY_PATH` 在 `app/` 里没有任何代码读取。
+- **私钥只有签发方需要** —— 也就是调用方（本地脚本、将来的登录接口、你们自己的前端后端）。
+
+因此生产部署时，服务进程所在机器**可以只挂公钥**，私钥留在签发方那边，泄露面更小。
+
+## 3. 生成密钥
+
+```powershell
+# 开发环境（默认输出到 config/jwt/dev，已被 .gitignore 忽略）
+D:\conda\envs\jr_py313\python.exe tools\generate_jwt_keys.py --out-dir config/jwt/dev
+```
+
+脚本会打印公钥指纹，并给出要写进 `.env` 的两行配置。已存在密钥时它**默认拒绝覆盖**，
+避免误操作把正在用的密钥冲掉（要换就得显式加 `--force`，见第 5 节）。
+
+克隆仓库后的完整起步动作：
+
+```powershell
+D:\conda\envs\jr_py313\python.exe tools\generate_jwt_keys.py --out-dir config/jwt/dev
+copy .env.example .env
+# 检查 .env 里这两行是否指向刚生成的密钥：
+#   JWT_PRIVATE_KEY_PATH=config/jwt/dev/jwt-private.pem
+#   JWT_PUBLIC_KEY_PATH=config/jwt/dev/jwt-public.pem
+```
+
+## 4. 最容易踩的坑：几个人连同一个服务，密钥必须一致
+
+- **自己起服务、自己调** → 自己生成一套密钥即可，互不干扰。
+- **连别人已经起好的服务** → **必须用那个服务正在用的私钥**，自己新生成一套会一直拿到
+  `401 AUTHENTICATION_REQUIRED`，而且错误信息不会告诉你"是密钥对不上"。
+
+判断依据很简单：**服务端用自己的公钥验签**。所以"我服务用哪把公钥"决定"谁能签出有效令牌"。
+
+自签令牌的参考实现：`tools/acceptance_check.py` 里的 `token()`（RS256 + 本地私钥）。
+
+## 5. 轮换密钥
+
+```powershell
+D:\conda\envs\jr_py313\python.exe tools\generate_jwt_keys.py --out-dir config/jwt/dev --force
+```
+
+**影响**：所有已签发的令牌**立即失效**（正在跑的脚本、前端缓存的令牌、别人手里的令牌都会变 401）。
+所以在低峰期做，并提前通知正在联调的人。开发阶段无所谓，生产环境要当变更来管。
+
+轮换后只需要重启服务（让它重新加载公钥），不需要改任何代码 —— 密钥路径是配置项，
+三个工具脚本（`acceptance_check`、`demo_agent_e2e`、`smoke_check`）也都从配置读路径。
+
+## 6. 生产环境
+
+```powershell
+# 在**生产机**上生成，不要把开发密钥拷过去
+python tools/generate_jwt_keys.py --out-dir /etc/jr-agent/keys
+```
+
+然后用环境变量覆盖（不要改代码里的默认值）：
+
+```ini
+JWT_PRIVATE_KEY_PATH=/etc/jr-agent/keys/jwt-private.pem
+JWT_PUBLIC_KEY_PATH=/etc/jr-agent/keys/jwt-public.pem
+JWT_ISSUER=<生产签发方标识>
+JWT_AUDIENCE=<生产受众>
+```
+
+注意 `JWT_ISSUER` / `JWT_AUDIENCE` 也应当与开发环境不同：`jwt.decode` 会校验这两个声明，
+生产沿用 `jr-local` 就等于允许开发环境签发的令牌在生产上生效。**这条比换密钥更容易被忽略。**
+
+## 7. 安全红线（脚本只能提醒，执行靠人）
+
+1. 私钥**永不进仓库**；换目录存放时确认新目录同样被 `.gitignore` 覆盖。
+2. 私钥**永不贴进聊天记录、工单、截图、CI 日志**。要分发就走内部共享盘或当面拷。
+3. 开发 / 生产**各一套**，互不复用；生产密钥在生产机生成，不做跨机拷贝。
+4. 有人员离开或密钥可能外泄时，按第 5 节轮换，并同步轮换 `JWT_ISSUER`（如有区分）。
+5. 服务端**不需要**私钥就不要放 —— 生产机上只挂公钥即可。
+
+## 8. 与"暂无登录接口"的关系
+
+当前底座**没有**"账号密码换令牌"的登录接口，令牌由外部按 RS256 自签。这是已知缺口，
+记为待办（见 `docs/19` 未解决项）。
+
+补充这个接口时，改动集中在签发侧：新增一个 `POST /auth/login`（校验密码 → 用私钥签令牌），
+验签侧（`JwtAuthenticator`）与身份解析侧（`IdentityService`）**都不需要改**。
+
+前提是一条接入红线：**业务代码只能从 `RequestContext` 取身份**，不许自己解析 JWT、
+不许硬编码 `user_id`、不许自己查 `sys_user` 判断角色。这条守住了，后补登录接口就是增量；
+破了，就得回头翻所有业务代码。