Harden auth/vault path sanitization and clean WeKnora docs

skills/mnote-vault/SKILL.md

@@ -1,8 +1,13 @@
 ---
 name: mnote-vault
 description: >
-  MNote AI 密码本（多 agent 唯一策略）。读密与 login/session：mnote-vault CLI + capability token（不依赖 mnote-web）。
+  【可全机】 MNote AI 密码本（多 agent 唯一策略）。读密与 login/session：mnote-vault CLI + capability token（不依赖 mnote-web）。
   登录态为每账号独立 session 文件；禁扫 .mnote/vault 文件。
+runtime: portable
+class: A
+host: local
+mcp_remote: null
+access: n/a
 ---
 
 # MNote 密码箱 / AI 密码本
@@ -11,6 +16,54 @@ description: >
 **设计**：
 - `design/12-vault/process/12-2-vaultd-local-token-agent-read-path-v1.md`（agent 读密 / login）
 - `design/12-vault/process/12-3-chrome-extension-vault-save-v1.md` §5.6 / §6.5（每账号 session 文件；扩展只写入）
+- `design/07-ai/process/7-76-ai-principal-web-pat-and-auth-hardening-v1.md`（Web PAT vs vault token）
+
+**本 skill 契约文件**（无 secret）：
+- `skills/mnote-vault/env.schema.json` — env 变量声明
+- `skills/mnote-vault/agent-env.example.env` — 本机 env 模板（复制后填值）
+
+## 三种凭证分职（必读 · 禁止混用）
+
+| 凭证 | 前缀 / 形态 | env | 用途 | 禁止 |
+|------|-------------|-----|------|------|
+| Vault capability | `mnv1.*` | `MNOTE_VAULT_TOKEN` / `MNOTE_VAULT_TOKEN_FILE` | `list/get/resolve/login/session` | 调 mnote-web 笔记 API |
+| Web PAT | `mnpat1.*` | `MNOTE_WEB_PAT`（或 `MNOTE_API_TOKEN`） | 机机访问笔记 JSON API | vault resolve / 当密码 |
+| 业务密钥 | 条目字段 | **无长期 env** | `resolve --field apikey\|password\|token` 短时使用 | 写入 skill / git / agent-env 常驻 |
+
+Scope 短名（与 CLI 一致）：`list,get,resolve,login,session`。  
+Web 设置页若传入 `vault.list` 等会在服务端归一化为短名。
+
+## Agent env 加载顺序
+
+```text
+1. 进程已有环境变量
+2. $MNOTE_AGENT_ENV_FILE（若设置）
+3. ~/.config/mnote/agent-env/<agent-name>.env
+4. 本 skill 默认：
+   MNOTE_VAULT_TOKEN_FILE=$HOME/.config/mnote/vault-tokens/default.token
+   MNOTE_AI_VAULT_ACTOR=mnote-e2e
+```
+
+本机布局（**0600，不进仓库**）：
+
+```text
+~/.config/mnote/
+  vault-tokens/
+    mnote-e2e.token      # AI 主体 / 多 agent 共享读密策略
+    <userId>.token       # 用户私有 agent（若代该用户读自己的箱）
+    default.token        # 兼容旧路径；新装建议按 subject 命名
+  agent-env/
+    paseo.env
+    default.env
+  vaultd-hmac.key        # 仅本机签发校验
+```
+
+**一主体一 token 文件**；禁止多人共用并互相覆盖 `default.token`。
+
+人在 **MNote 设置 → API 访问令牌 / 密码箱 AI 访问** 签发后：
+1. 复制 token 或「安装命令」
+2. 写入 `vault-tokens/<subject>.token` 与/或 `agent-env/<agent>.env`
+3. agent：`set -a; source ~/.config/mnote/agent-env/<agent>.env; set +a`
 
 ## 读密稳态（P0 · 不依赖 mnote-web）
 
@@ -24,21 +77,24 @@ description: >
 
 ```bash
 # 一次（人 / 安装）：签发 token（cwd 任意）
+# CLI：
 mnote-vault issue-token --agent paseo --ttl 90d
-# 或绝对路径：
-# /home/lix/.local/bin/mnote-vault issue-token --agent paseo --ttl 90d
+# 或 Web 设置页「密码箱 AI 访问」签发 → 安装到 vault-tokens/<subject>.token
 
 # Agent 每次（已知 id；cwd 任意，不要求在 mnote 仓库）
+# 可选：source ~/.config/mnote/agent-env/<agent>.env
 export MNOTE_VAULT_TOKEN_FILE="${MNOTE_VAULT_TOKEN_FILE:-$HOME/.config/mnote/vault-tokens/default.token}"
 mnote-vault list
 mnote-vault resolve --id <id> --field password
 # 管道只要明文：
 mnote-vault resolve --id <id> --field password --raw
+# 上游 API Key：
+mnote-vault resolve --id <id> --field apikey --raw
 ```
 
 **故障排查顺序**（≤2 步，禁止全盘搜索二进制）：
 1. `command -v mnote-vault || ls /home/lix/.local/bin/mnote-vault`
-2. `mnote-vault doctor` → `tokenValid=false` 时只跑 `issue-token`，**不要**起 3000
+2. `mnote-vault doctor` → `tokenValid=false` 时只跑 `issue-token` 或 Web 重签并安装文件，**不要**起 3000
 
 | 命令 | 用途 |
 |------|------|
@@ -114,6 +170,9 @@ mnote-vault login --id <id> --force-refresh
 ## 硬规则
 
 1. 禁 file 扫 `.mnote/vault/**`（含 sessions）  
-2. 聊天不贴 password / cookieHeader / token  
-3. Token `0600`；故障先 `issue-token`，不要默认起 3000  
+2. 聊天不贴 password / cookieHeader / token / PAT  
+3. Token 文件 `0600`；故障先 `issue-token` 或 Web 重签安装，不要默认起 3000  
 4. 需要登录态时 **先 `login`**，不要先 `resolve` 密码再手拼 Cookie  
+5. **分职**：笔记 CRUD 用 `MNOTE_WEB_PAT`；读密用 `mnv1`；业务 API Key 只 `resolve`，不进 skill 源码  
+6. Skill 只声明 env 契约；secret 只在 `~/.config/mnote/**`  
+7. 多 agent 共享读密 → 默认 AI 主体 `mnote-e2e` token + 用户 share-to-AI；用户私有 agent 才持该用户 token