5f23cf85b1
All checks were successful
Push & PR Check / check (pull_request) Successful in 1m7s
Rules-Applied: R03,R13
159 lines
15 KiB
Markdown
159 lines
15 KiB
Markdown
---
|
||
id: project-resource-broker
|
||
name: 项目资源与凭证代办
|
||
status: done
|
||
progress: 100
|
||
---
|
||
|
||
## 概述
|
||
|
||
让项目 Agent 发现“某项资源是否可用”，并通过炼境调用有限、可审计的操作；Agent 不需在对话、MCP 输出、项目文件中接收原始凭证。统一的是入口与操作契约，不是把所有项目密钥集中到炼境一处。
|
||
|
||
## 设计决策：按用途存放，按操作代办（2026-09-23）
|
||
|
||
### 背景与证据
|
||
|
||
- `api_keys.api_key`、`gitea_instances.access_token`、`gitea_repos.webhook_secret` 目前是 SQLite 文本列；`get_api_keys`、`gitea_list_instances`、部分仓库 DTO 会将原值返回 Tauri 前端。`ApiKeysPanel` 的遮罩发生在前端，不能当作后端不暴露。
|
||
- 现有 MCP `create_pull_request(project_id, ...)` 已由炼境内部使用 Gitea token，调用方不需要提取 token。应以此为首个资源代办样板，不另造 PR 接口。
|
||
- 现有 `/mcp/projects/<project_id>` 只提供单机误操作隔离，并非认证或不同 OS 进程间的秘密隔离。Agent 若与用户共享 Windows 账户，不能宣称其物理上绝对读不到本机凭证。
|
||
- Enterprise System 的 production 链路保留 Gitea Actions、项目部署脚本和服务器运行环境；炼境当前只读同 SHA 交付证据，不得由本模块扩张为 SSH、数据库、migration 或部署执行者。
|
||
|
||
### 方案选择
|
||
|
||
| 方案 | 收益 | 代价 / 风险 | 结论 |
|
||
| --- | --- | --- | --- |
|
||
| 将全部 `.env`、CI、服务器凭证导入炼境，提供通用 `get_secret` | 表面上配置统一 | 单点风险、同用户 Agent 可读取、破坏 CI/运行时现有信任边界 | 否决 |
|
||
| 维持现状，仅增加“不要读取密钥”的 Skill 提醒 | 改动少 | 明文存储与原值 DTO 仍在，无法形成可验证边界 | 否决 |
|
||
| **按执行用途保留凭证原位；炼境仅托管本机代办凭证引用和最小操作** | 复用已有 PR 能力，渐进迁移，Agent 只见状态和操作结果 | 需兼容旧数据，且同用户本机威胁模型有限 | **选定** |
|
||
|
||
### 凭证归属与边界
|
||
|
||
| 用途 | 凭证权威位置 | 炼境职责 | Agent 可见 |
|
||
| --- | --- | --- | --- |
|
||
| 本机 Gitea API 代办 | Windows 用户保护的本机凭证存储；SQLite 仅保存稳定引用与非秘密元数据 | 在项目已绑定 Gitea 仓库且操作被允许时，代办现有 PR/状态调用 | `configured / unavailable / needs_repair` 与 PR 结果；无 token |
|
||
| Gitea Actions 中的 CI/部署 | Gitea Actions secrets | 只读检查 CI 与交付证据 | 状态与证据引用；无 secret |
|
||
| 项目进程的数据库、第三方服务、服务器运行时 | 项目自己的运行环境 / 云端现有机制 | 首轮只报告资源是否已配置，不接管值 | 非秘密 readiness；无连接串、账号密码 |
|
||
| 开发者手工保存的通用 API Key | 炼境本机受保护存储（通过单独迁移卡处理） | 保留人的显式展示/复制操作；不提供 MCP 原值读取 | 常态列表仅元数据；Agent 不获 reveal 工具 |
|
||
|
||
首轮不增加任意 URL/命令代理，不增加 `get_secret` / `export_env` / `run_sql` / `ssh_exec` / `deploy`。新操作的授权必须在能力本体服务层检查项目绑定、目标、动作；不能靠前端置灰或 MCP 描述约束。写操作沿用现有确认与 Git/PR 规则。读取的资源状态不得含凭证、用户名、连接串、敏感目标详情。若将来要求抵抗同一 OS 用户下的恶意进程，需另立认证与进程隔离设计，不能拿 loopback/scoped URL 充当安全边界。
|
||
|
||
### 受影响文件与数据流
|
||
|
||
- 现有读取：`src-tauri/src/commands/api_keys.rs`、`src-tauri/src/commands/gitea.rs`、`src-tauri/src/db.rs`；前端契约 `src/lib/commands.ts`，展示 `src/components/dashboard/ApiKeysPanel.tsx`、`src/components/dashboard/GiteaPanel.tsx`。
|
||
- 建议新增：`src-tauri/src/credential_store.rs`，隔离 Windows 凭证存储与可注入测试接口；实际 API/依赖在卡 R3 的技术验证后固定。Rust 模块入口需在 `src-tauri/src/lib.rs` 注册。
|
||
- 建议新增只读状态：后端项目资源 readiness 聚合函数，并由 `src-tauri/src/mcp_tools.rs` 公开项目 scoped 查询；`src/lib/commands.ts` 提供同一本体的人类投影。v1 仅 Gitea 绑定、凭证可用性等非秘密状态，不泛化所有 provider。
|
||
- 外部契约变化须同步 `docs/ai-context/project-context.yaml` 和相关调用说明。任何 SQLite schema 改动须在 `src-tauri/src/db.rs::migrate()` 中添加兼容迁移，不能更改旧安装数据的含义或静默清空。
|
||
|
||
### 迁移与失败模型
|
||
|
||
1. 先增加脱敏 DTO 与回归测试；人的 API Key 展示/复制改为显式动作，常态列表不携带原值。此步骤不删 SQLite 原值。
|
||
2. 以 Windows Credential Manager 为优先候选，在隔离测试中验证写入、读取、覆盖、删除、用户上下文、重启后读取与错误返回；若不满足要求，停止迁移并重新决策，不静默退回明文 SQLite。
|
||
3. 迁移每条旧凭证时采取“写新存储 → 读取校验 → 切换引用 → 再清除旧列”的可恢复顺序；失败保留旧值并显示 `needs_repair`，不把失败伪装为 `not_configured`。设计并演练备份/恢复后再动真实用户数据；旧数据库备份可能仍含明文，不能宣称迁移后历史明文已消失。
|
||
4. 凭证存储不可用时，代办操作 fail closed，项目自有 CI/运行链路照常；状态明确提示缺少/不可用/需修复，日志、错误文本和测试快照均不得回显原值。
|
||
|
||
### 验证路径
|
||
|
||
- 载体：Rust 纯函数及带内存数据库/模拟凭证存储的 `cargo test`；MCP 只读工具做真实 loopback/scoped 握手验证；前端展示由人终验。
|
||
- 示例：`[cargo test] gitea_list_instances()` → JSON 不含 `access_token`；`get_project_resource_status(p1)` → 仅非秘密状态，p2 参数被 scope 拒绝。
|
||
- 示例：`[cargo test] migrate_legacy_credential(模拟存储失败)` → 旧值仍可恢复、状态为 `needs_repair`、不泄露凭证。
|
||
- 示例：`[MCP] create_pull_request(p1, head, base, title)` → 返回 PR 标识或可行动错误，不返回 token；不把生产部署作为测试副作用。
|
||
|
||
### 风险与决策闸门
|
||
|
||
- **同一 Windows 用户可读性**：本方案减少凭证进入 Agent 上下文与普通 DTO 的机会，不提供强进程隔离；验收不能写成“Agent 绝对无法获取”。
|
||
- **旧用户数据迁移风险**：先用复制的匿名/模拟 DB 演练失败与回滚，再对真实数据执行；无验证、无备份方案不得迁移。
|
||
- **功能回退风险**：API Key 显示/复制保留为人的显式操作；Gitea PR 创建和 webhook 签名必须回归。
|
||
- **`Cargo.toml` 当前有既有未提交改动**：实施存储 adapter 若需改依赖，先确定改动归属并使用隔离工作区；不得混合提交或覆盖。
|
||
- **范围膨胀风险**：Enterprise 非生产样板只验证一个真实操作；是否扩展第二种资源，由减少 Agent 阻塞次数、人工取密次数、失败定位耗时的实测结果决定。
|
||
|
||
## 任务拆解
|
||
|
||
### ✅ R10 — scoped MCP 合成 PR 端到端回归
|
||
- status: done
|
||
- complexity: M
|
||
- files: src-tauri/src/mcp_server.rs
|
||
- depends: R4, R7, R8
|
||
- acceptance: "agent_verify: [cargo test] scoped_mcp_create_pull_request_uses_synthetic_credential → 真实 127.0.0.1 MCP initialize/tools/list/tools/call 经项目作用域到模拟 Gitea；请求使用合成受保护凭据，结果仅含 PR 标识、不含 token，跨项目参数拒绝；测试后合成凭据引用被清理。[CLI] cargo test、git diff --check 通过。human_verify: 无（仅合成测试，不接触真实仓库）。"
|
||
- retrospective: "【复盘】scoped MCP 合成 PR 端到端回归｜任务类型: MCP工具｜复杂度: M｜实际轮数: 2轮（预估 2 轮）｜是否返工: 是｜返工原因: 初版模拟服务无接入超时且清理守卫建立偏晚｜有效策略: 内存数据库 + 随机 Windows 凭据引用 + 127.0.0.1 mock，复用真实 MCP 路由并在 Drop 中清理｜遗留风险: 该串联测试仅在 Windows 执行；真实 Gitea 试点仍需单独授权｜auto_applied_rules: R13｜rule_effectiveness: R13=有效"
|
||
|
||
### ✅ R9 — PR 审查修复：缓存失效、凭证删除与 readiness
|
||
- status: done
|
||
- complexity: M
|
||
- files: src/components/dashboard/ApiKeysPanel.tsx, src/components/dashboard/ApiKeysPanel.test.ts, src-tauri/src/credential_store.rs, src-tauri/src/commands/api_keys.rs, src-tauri/src/commands/gitea.rs, src/lib/commands.ts
|
||
- acceptance: "agent_verify: [cargo test] 凭证删除失败可恢复且不会假成功，legacy readiness 为 pending_migration 而非 configured；[vitest] copyCurrentApiKey 编辑后复制最新值；[CLI] typecheck、测试与 git diff --check 通过。human_verify: 正式安装版编辑后显示/复制终验。"
|
||
- human_verify: pending（正式安装版 UI 未在本轮重跑；agent 路径已通过）
|
||
|
||
### ✅ R1 — Gitea 与 webhook 输出脱敏
|
||
- status: done
|
||
- complexity: M
|
||
- files: src-tauri/src/commands/gitea.rs, src/lib/commands.ts
|
||
- depends: gitea-integration
|
||
- acceptance: "agent_verify: [cargo test] gitea_list_instances / gitea_repo DTO 序列化 → 不含 access_token 或 webhook_secret；原有 Gitea 连接测试仍通过。human_verify: 设置页能显示实例并执行改 Token，不在常态 UI 或调试响应显示原值。"
|
||
- human_verify: pending（需用户在隔离功能交付后终验真实 UI；agent 验证已通过）
|
||
|
||
### ✅ R2 — API Key 常态列表脱敏与人的显式查看
|
||
- status: done
|
||
- complexity: M
|
||
- files: src-tauri/src/commands/api_keys.rs, src/lib/commands.ts, src/components/dashboard/ApiKeysPanel.tsx
|
||
- depends: R1
|
||
- acceptance: "agent_verify: [cargo test] get_api_keys() → 列表序列化不含 api_key，显式 reveal 按不存在 id 返回错误，MCP tools/list 无 reveal 工具。human_verify: 人主动点击后仍可查看/复制，默认列表不显示原值。"
|
||
- human_verify: pending（需用户终验显式查看/复制；agent 验证已通过）
|
||
|
||
### ✅ R3 — Windows 本机凭证存储可行性与适配接口
|
||
- status: done
|
||
- complexity: M
|
||
- files: src-tauri/src/credential_store.rs, src-tauri/src/lib.rs
|
||
- depends: R2
|
||
- acceptance: "[cargo test] 凭证存储适配器在模拟存储上完成 put/get/replace/delete 与失败注入；Windows 隔离测试重启后按引用读取同一测试值，失败时不回显值；不满足则停止后续迁移并记录证据。"
|
||
|
||
### ✅ R4 — Gitea 凭证兼容迁移与代办回归
|
||
- status: done
|
||
- complexity: M
|
||
- files: src-tauri/src/db.rs, src-tauri/src/commands/gitea.rs, src-tauri/src/commands/git_ops.rs, src-tauri/src/credential_store.rs
|
||
- depends: R1, R3
|
||
- acceptance: "[cargo test] 旧 Gitea token 在模拟数据库中 write→verify→switch→clear；注入存储失败时旧值可恢复且状态 needs_repair；create_pull_request 与 webhook 注册仍使用有效凭证，响应不含 token。"
|
||
|
||
### ✅ R5 — webhook 签名凭证兼容迁移
|
||
- status: done
|
||
- complexity: M
|
||
- files: src-tauri/src/db.rs, src-tauri/src/commands/gitea.rs, src-tauri/src/mcp_webhook.rs, src-tauri/src/credential_store.rs
|
||
- depends: R1, R3, R4
|
||
- acceptance: "[cargo test] 已登记 webhook_secret 的旧仓库经 write→verify→switch→clear 后仍可验证 webhook 签名；模拟存储失败时旧值可恢复，仓库 DTO 与日志均不含 secret。"
|
||
|
||
### ✅ R6 — API Key 凭证兼容迁移与显式查看回归
|
||
- status: done
|
||
- complexity: M
|
||
- files: src-tauri/src/db.rs, src-tauri/src/commands/api_keys.rs, src-tauri/src/credential_store.rs, src/components/dashboard/ApiKeysPanel.tsx, src/lib/commands.ts
|
||
- depends: R2, R3
|
||
- acceptance: "[cargo test] 旧 API Key 迁移后列表仍无原值，人的显式 reveal 返回原值；模拟迁移失败保留可恢复数据且不产生半迁移的假成功。"
|
||
|
||
### ✅ R7 — 项目资源只读 readiness 与操作边界
|
||
- status: done
|
||
- complexity: M
|
||
- files: src-tauri/src/commands/gitea.rs, src-tauri/src/mcp_tools.rs, src-tauri/src/mcp_server.rs, src-tauri/src/lib.rs, src/lib/commands.ts
|
||
- depends: R4, R5
|
||
- acceptance: "[cargo test] get_project_resource_status(p1) → configured/unavailable/needs_repair 有来源且不含凭证；p2 越界被拒绝；MCP tools/list 无 get_secret、任意 HTTP/SSH/SQL 代理。"
|
||
|
||
### ✅ R8 — 契约文档与 Enterprise 非生产样板终验
|
||
- status: done
|
||
- complexity: M
|
||
- files: docs/ai-context/project-context.yaml, docs/ai-context/agent-button-system.md, docs/ai-context/project-brief.md, AGENTS.md, .blueprint/manifest.yaml, .blueprint/modules/project-resource-broker.md
|
||
- depends: R6, R7
|
||
- acceptance: "agent_verify: [MCP] Enterprise 项目调用只读 resource status → 返回非秘密 readiness；[cargo test] 模拟 Gitea 调用 create_pull_request → 仅返回 PR 标识/可行动错误，日志与调用结果无原始凭证；[CLI] git diff --check → exit 0。human_verify: 确认 Gitea/CI/服务器凭证仍在原用途位置，未创建真实 PR、触发生产部署或数据库写入。"
|
||
- human_verify: pending（真实 UI 与凭证归属留待用户终验；agent 非生产路径已通过）
|
||
|
||
## 实施验证（合成数据，未接触真实生产密钥）
|
||
|
||
- R1–R2：DTO/API Key 常态列表序列化测试通过；人的显式 API Key reveal 只在本机 Tauri command，MCP 不暴露。
|
||
- R3：Windows Credential Manager 随机测试引用跨进程读取并清理；模拟存储的写、读、覆盖、删除与失败注入通过。
|
||
- R4–R6：旧值迁移、存储/数据库失败保留旧值、SQLite 迁移前备份及恢复演练、新建/更新/删除回归通过；模拟 Gitea PR 与 webhook 注册均只访问 `127.0.0.1`。
|
||
- R7–R8：内存 Enterprise fixture 经真实 loopback MCP HTTP/SSE 完成 `initialize → tools/list → tools/call`，readiness 不含凭证，跨项目参数被拒绝。
|
||
- R10：Windows 合成项目经真实 scoped MCP `initialize → tools/list → tools/call(create_pull_request)` 到 `127.0.0.1` 模拟 Gitea；代办内部使用受保护存储的合成 token，Agent 结果仅含 PR 信息，跨项目参数被拒绝，测试后凭据引用清理；全量 Rust 测试通过（211 passed、1 ignored）。
|
||
- 未验证：真实用户 DB/凭证迁移、真实 Gitea/CI/服务器、正式安装版 UI 人工终验和真实 PR/部署；现有备份若不含当前旧值会拒绝迁移并要求人工安排新备份，不会降级明文。
|
||
|
||
## 阶段退出标准
|
||
|
||
- P0（R1–R2）：普通列表/DTO 不再携带原始值；不误称数据库已加密。
|
||
- P1（R3–R6）：本机代办凭证的受保护存储与兼容迁移可恢复，现有 Gitea/API Key/webhook 能力不回退。
|
||
- P2（R7–R8）：Agent 能获取 Enterprise 的非秘密 readiness，PR 代办通过模拟 Gitea 验证；真实 PR 试用需另行按交付流程授权。量化是否真减少人工传密和失败定位时间；未达到收益门槛，不扩成通用 Vault。
|