mnote/skills/mnote-vault/SKILL.md

---
name: mnote-vault
description: >
  【可全机】 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 密码本

**SSOT**：`/home/lix/.agent-infra/vault-policy.md`  
**设计**：
- `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）

### 可执行入口（agent 必看 · 不要自己 find）

| 优先级 | 路径 | 说明 |
|--------|------|------|
| **1（默认）** | `mnote-vault` | 已装到 `~/.local/bin/mnote-vault`（symlink） |
| **2（绝对路径）** | `/home/lix/.local/bin/mnote-vault` | PATH 异常时直接用 |
| **3（源码构建产物）** | `/mnt/Data1T/mnote/rust/target/debug/mnote-vault` | 开发树；**不要**在 `/home/lix` 下 `find` 全盘 |

```bash
# 一次（人 / 安装）：签发 token（cwd 任意）
# CLI：
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` 或 Web 重签并安装文件，**不要**起 3000

| 命令 | 用途 |
|------|------|
| `doctor` | workspace / token / hmac 状态（无明文） |
| `issue-token` | 签发 capability token（**不是** master key） |
| `whoami` | 当前 token claims |
| `list` / `get` | L0 选型；无密码/cookie 明文；可见 `hasLoginSession` |
| `resolve` | **取密**；字段 `password` / `apikey` / `token` 等；审计无 value |
| `login` | **优先复用登录态**；无/过期则 api_first 或 human_required |
| `session` | 浏览器/人机验证后回写 Cookie（写 session 文件；不启 3000） |
| `serve` | 可选 UDS vaultd；CLI 默认 sock→内嵌 fallback |

**禁止**：为读密 / login / session 去 `auth-e2e` / 起 3000 / 用 cookie 调 `/api/vault/ai/*`。  
**禁止**：`Read` / `cat` / `grep` `.mnote/vault/**`（含 `entries/` 与 `sessions/`）。  
`scripts/mnote-vault-cli.js` 的 web 路径仅调试 UI。

## 登录态文件（每账号一份 · 12-3）

磁盘（AI 本 / 用户 vault 同结构）：

```text
{workspace}/.mnote/vault/
  entries/{credId}.md              # 账号密码；勿手读
  sessions/{credId}/primary.json   # 主账号登录态
  sessions/{credId}/{accountId}.json
```

- **写入口（人）**：Chrome 扩展默认保存登录态 → `PUT …/session`；或 Agent `mnote-vault session`。  
- **读入口（AI）**：只经 `login` / `session` /（P1）`resolve --field session`。  
- frontmatter 内旧 `loginSession`：兼容读；**新写一律走 session 文件**。  
- 扩展写入的是**人用 vault**；Agent 默认读 **AI 本** → 须用户 **share-to-ai**（会连同 session 文件复制）。

## 登录稳态（外站 cookie · 12-2 P1d + 12-3）

需要外站已登录状态（Cookie）时：

```bash
# 1) 优先复用已有 session（读 sessions/…json；无 HTTP 出站）
mnote-vault login --id <id>
# 多账号：
mnote-vault login --id <id> --account-id <accId>

# 2a) mode=session | reused | ok → 用响应里的 cookieHeader
#     （仅进程内/管道使用；禁止贴进聊天、commit、issue）

# 2b) human_required / CF：chrome-bridge 登录后回写
mnote-vault session --id <id> --cookie-header 'name=value; …' --source human_bridge
# 可选：--account-id <accId>

# 3) 强制重新 api_first 登录（忽略未过期 session）
mnote-vault login --id <id> --force-refresh
```

| `login` 结果 | Agent 动作 |
|--------------|------------|
| `mode=session` / `reused` / `ok` 且含 `cookieHeader` | 用 Cookie 调目标站 API 或注入浏览器 |
| `mode=human_required` | chrome-bridge / 人完成验证 → `session` 回写 → 再 `login` |
| 无 session 且 api_first 失败 | 查 playbook / 人用扩展是否已 share-to-ai |

- `resolve` / `session` / `login` 写盘：本地 `.mnote/vault/**`（core），**不**经 mnote-web。  
- `login` 的 `api_first` 仅对目标站出站 HTTP。  
- 默认 session TTL：7 天（`MNOTE_VAULT_SESSION_TTL_HOURS`）。

## 与 Chrome 扩展的边界

| 角色 | 通道 | 鉴权 |
|------|------|------|
| 人：外站保存账号+登录态 | 扩展 → mnote-web `/api/vault/*` | human Bearer（**非** agent token） |
| AI：读密 / 复用登录态 | `mnote-vault` CLI → core | capability token |

扩展 **不是** agent 通道。人保存后若要 AI 用：在确认层勾选 **同步到 AI 密码本**（或工作台 share-to-ai）。

## 硬规则

1. 禁 file 扫 `.mnote/vault/**`（含 sessions）  
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