@ -0,0 +1,142 @@
---
id: project-resource-broker
name: 项目资源与凭证代办
status: done
progress: 100
---
## 概述
让项目 Agent 发现“某项资源是否可用”， ；
## 设计决策： ， （ ）
### 背景与证据
- `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， ，
- 现有 `/mcp/projects/<project_id>` 只提供单机误操作隔离，并非认证或不同 OS 进程间的秘密隔离。Agent 若与用户共享 Windows 账户，不能宣称其物理上绝对读不到本机凭证。
- Enterprise System 的 production 链路保留 Gitea Actions、项目部署脚本和服务器运行环境；
### 方案选择
| 方案 | 收益 | 代价 / 风险 | 结论 |
| --- | --- | --- | --- |
| 将全部 `.env` 、CI、服务器凭证导入炼境， `get_secret` | 表面上配置统一 | 单点风险、同用户 Agent 可读取、破坏 CI/运行时现有信任边界 | 否决 |
| 维持现状，仅增加“不要读取密钥”的 Skill 提醒 | 改动少 | 明文存储与原值 DTO 仍在，无法形成可验证边界 | 否决 |
| **按执行用途保留凭证原位；炼境仅托管本机代办凭证引用和最小操作** | 复用已有 PR 能力， ， **选定** |
### 凭证归属与边界
| 用途 | 凭证权威位置 | 炼境职责 | Agent 可见 |
| --- | --- | --- | --- |
| 本机 Gitea API 代办 | Windows 用户保护的本机凭证存储； `configured / unavailable / needs_repair` 与 PR 结果；无 token |
| Gitea Actions 中的 CI/部署 | Gitea Actions secrets | 只读检查 CI 与交付证据 | 状态与证据引用；无 secret |
| 项目进程的数据库、第三方服务、服务器运行时 | 项目自己的运行环境 / 云端现有机制 | 首轮只报告资源是否已配置，不接管值 | 非秘密 readiness；
| 开发者手工保存的通用 API Key | 炼境本机受保护存储（通过单独迁移卡处理） | 保留人的显式展示/复制操作；不提供 MCP 原值读取 | 常态列表仅元数据；
首轮不增加任意 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，
### 验证路径
- 载体： `cargo test` ；
- 示例：`[cargo test] gitea_list_instances()` → JSON 不含 `access_token` ； ，
- 示例：`[cargo test] migrate_legacy_credential(模拟存储失败)` → 旧值仍可恢复、状态为 `needs_repair` 、不泄露凭证。
- 示例：`[MCP] create_pull_request(p1, head, base, title)` → 返回 PR 标识或可行动错误，不返回 token；
### 风险与决策闸门
- **同一 Windows 用户可读性** ：本方案减少凭证进入 Agent 上下文与普通 DTO 的机会， ；
- **旧用户数据迁移风险** ：先用复制的匿名/模拟 DB 演练失败与回滚，再对真实数据执行；无验证、无备份方案不得迁移。
- **功能回退风险** ： ；
- ** `Cargo.toml` 当前有既有未提交改动**：实施存储 adapter 若需改依赖，先确定改动归属并使用隔离工作区；不得混合提交或覆盖。
- **范围膨胀风险** ：
## 任务拆解
### ✅ 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； ，
- human_verify: pending（ ；
### ✅ 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， ，
- human_verify: pending（ ；
### ✅ 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 与失败注入；
### ✅ 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； ；
### ✅ 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 有来源且不含凭证； ；
### ✅ 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；
- human_verify: pending（ ；
## 实施验证（合成数据，未接触真实生产密钥）
- R1– ： ，
- R3：
- R4– ： `127.0.0.1` 。
- R7– ： `initialize → tools/list → tools/call` ，
- 未验证：真实用户 DB/凭证迁移、真实 Gitea/CI/服务器、正式安装版 UI 人工终验和真实 PR/部署；现有备份若不含当前旧值会拒绝迁移并要求人工安排新备份，不会降级明文。
## 阶段退出标准
- P0（ – ） ：
- P1（ – ） ： ，
- P2（ – ） ： ，