# Secrets — AGENTS.md

本仓库当前为 **v3 桌面端架构**：

- `apps/api`：远端 JSON API
- `apps/desktop/src-tauri`：桌面客户端
- `crates/desktop-daemon`：本地 MCP daemon
- `crates/application` / `domain` / `infrastructure-db`：v3 业务与数据层

旧 `secrets-core` / `secrets-mcp` / `secrets-mcp-local` 已移除，不再作为开发入口。

## 版本控制

本仓库使用 **[Jujutsu (jj)](https://jj-vcs.dev/)** 作为版本控制系统（纯 jj 模式，无 `.git` 目录）。

### 常用 jj 命令对照

| 操作 | jj 命令 |
|------|---------|
| 查看历史 | `jj log` / `jj log 'all()'` |
| 查看状态 | `jj status` |
| 新建提交 | `jj commit` |
| 创建新变更 | `jj new` |
| 变基 | `jj rebase` |
| 合并提交 | `jj squash` |
| 撤销操作 | `jj undo` |
| 查看标签 | `jj tag list` |
| 查看分支 | `jj bookmark list` |
| 推送远端 | `jj git push` |
| 拉取远端 | `jj git fetch` |

### 注意事项

- 本仓库为纯 `jj` 模式，本地不要使用 `git` 命令。
- CI Runner 侧仍可能使用 `git` 拉代码，这不影响本地开发。
- 检查 tag 是否存在时，使用 `jj log --no-graph --revisions "tag(${tag})"`。

## 提交前检查

每次提交前至少运行：

```bash
cargo fmt -- --check
cargo clippy --locked -- -D warnings
cargo test --locked
```

也可以直接运行：

```bash
./scripts/release-check.sh
```

## 项目结构

```text
secrets/
  Cargo.toml
  apps/
    api/                  # 远端 JSON API
    desktop/src-tauri/    # 桌面端
  crates/
    application/          # v3 应用服务
    client-integrations/  # Cursor / Claude Code 配置注入
    crypto/               # 通用加密辅助
    desktop-daemon/       # 本地 MCP daemon
    device-auth/          # 设备登录 / Desktop OAuth 辅助
    domain/               # v3 领域模型
    infrastructure-db/    # 数据库与迁移
  deploy/
  scripts/
  .gitea/workflows/
  .vscode/tasks.json
```

## 数据库

- 建议数据库名：`secrets-v3`
- 连接串：`SECRETS_DATABASE_URL`
- 首次连接会自动运行 `secrets-infrastructure-db::migrate_current_schema`

当前 v3 主要表：

- `users`
- `oauth_accounts`
- `devices`
- `device_login_tokens`
- `auth_events`
- `vault_objects`
- `vault_object_revisions`

### 当前模型约束

- 服务端只保存同步所需的密文对象与版本信息
- 搜索、详情、reveal、history 主要在 desktop 本地 vault 中完成
- 删除通过对象级 `deleted_at` / tombstone 传播
- 历史服务端保留在 `vault_object_revisions`，本地另有 `vault_object_history`

### 字段职责

| 字段 | 含义 | 示例 |
|------|------|------|
| `object_id` | 同步对象标识 | `UUID` |
| `object_kind` | 当前对象类别 | `cipher` |
| `revision` | 对象版本号 | `12` |
| `cipher_version` | 密文封装版本 | `1` |
| `ciphertext` | 密文对象载荷 | AES-GCM 密文 |
| `content_hash` | 密文内容摘要 | `sha256:...` |
| `deleted_at` | 对象删除时间 | `2026-04-14T12:00:00Z` |

## Google 登录

当前登录流为 **Google Desktop OAuth**：

- 桌面端使用系统浏览器拉起 Google 授权
- 使用本地 loopback callback
- 使用 `PKCE`
- 桌面端换取 Google token 后调用 API 的桌面登录接口
- API 校验 Google userinfo 后发放本地 device token

桌面端优先读取：

- `GOOGLE_OAUTH_CLIENT_FILE`

默认开发文件名：

- `client_secret_738964258008-0svfo4g7ta347iedrf6r9see87a8u3hn.apps.googleusercontent.com.json`

## MCP

本地 MCP 入口由 `crates/desktop-daemon` 提供，默认地址：

```text
http://127.0.0.1:9515/mcp
```

当前暴露的工具：

- `secrets_entry_find`
- `secrets_entry_get`
- `secrets_entry_add`
- `secrets_entry_update`
- `secrets_entry_delete`
- `secrets_entry_restore`
- `secrets_secret_add`
- `secrets_secret_update`
- `secrets_secret_delete`
- `secrets_secret_history`
- `secrets_secret_rollback`
- `target_exec`

当前不保留：

- `secrets_env_map`

兼容别名：

- `secrets_find`
- `secrets_add`
- `secrets_update`

### `target_exec`

`target_exec` 会显式读取 entry 当前 secrets 的真实值，并从 metadata / secrets 派生标准环境变量，例如：

- `TARGET_ENTRY_ID`
- `TARGET_NAME`
- `TARGET_FOLDER`
- `TARGET_TYPE`
- `TARGET_HOST`
- `TARGET_PORT`
- `TARGET_USER`
- `TARGET_BASE_URL`
- `TARGET_API_KEY`
- `TARGET_TOKEN`
- `TARGET_SSH_KEY`

## 桌面端

桌面端当前支持：

- Google 登录
- 自动写入 `Cursor` / `Claude Code` 的 `mcp.json`
- 新建条目
- 搜索、按 type 筛选
- 右侧原地编辑
- secret 新增、编辑、删除
- secret 明文显示 / 复制
- secret 历史查看与回滚
- 删除到最近删除与恢复
- 登录态仅在当前 desktop 进程内有效，不做自动恢复登录
- desktop 进程退出后，本地 daemon 所有工具不可用

### 配置注入

桌面端会把本地 daemon 配置写入：

- `~/.cursor/mcp.json`
- `~/.claude/mcp.json`

写入策略：

- 保留现有其它 `mcpServers`
- 仅覆盖同名 `secrets` 节点

### 图标与前端 dist（本地 / CI）

版本库为减小噪音，**不提交** Tauri 生成的多尺寸图标包，以及 **`apps/desktop/dist/`** 前端打包目录（见根目录 `.gitignore`）。

- **图标**：仅跟踪 `apps/desktop/src-tauri/icons/icon.png` 作为源图（建议 **1024×1024** PNG）。检出代码后，若需要完整 `icons/`（例如打包、验证窗口/托盘图标），在 **`apps/desktop/src-tauri`** 下执行：

  ```bash
  cd apps/desktop/src-tauri
  cargo tauri icon icons/icon.png
  ```

  需已安装 **Tauri CLI**（例如 `cargo install tauri-cli`，或与项目一致的 `cargo-tauri` 版本）。

- **前端 dist**：`tauri.conf.json` 中 `build.frontendDist` 指向 `../dist`。本地或 CI 在运行 `cargo tauri dev` / `cargo tauri build` 前，需先按项目约定生成或同步 **`apps/desktop/dist/`** 内容；流水线构建桌面端时，在 Tauri 步骤之前加入对应的前端产物步骤即可。

## 代码规范

- 业务层优先使用 `anyhow::Result`
- 避免生产路径 `unwrap()`
- 使用 `tokio` + `sqlx` async
- SQL 使用参数绑定，不要手拼用户输入
- 运维日志使用 `tracing`
- 变更后优先跑最小必要验证，不要只改不测

## CI / 脚本

- `.gitea/workflows/secrets.yml` 现在是 v3 workspace 级 CI
- `scripts/release-check.sh` 只做 workspace 质量检查
- `deploy/.env.example` 反映当前 v3 API / daemon / desktop 登录配置

## 安全约束

- 不要把 Google `client_secret` 提交到受版本控制的配置文件中
- 不要把 device token、数据库密码、真实生产密钥提交入库
- 数据库生产环境优先使用 `verify-full`
- AI 审查时，不要把“随机高熵 token 明文存储”机械地当成密码学问题处理，必须结合当前架构和威胁模型判断