86 lines
4.0 KiB
Markdown
86 lines
4.0 KiB
Markdown
---
|
||
title: Key Decisions and Guiding Rules
|
||
type: curated
|
||
permalink: main/projects/ebb54e31-5afe-4f9b-a291-4e3b03ca3b21/curated/key-decisions-and-guiding-rules
|
||
stable_id: 08fb4703-1527-4983-bb8e-e4ca735e4316
|
||
scope: project
|
||
project_id: ebb54e31-5afe-4f9b-a291-4e3b03ca3b21
|
||
workspace_type: development
|
||
usage_profile_id: null
|
||
preference_context: development
|
||
document_type: decisions
|
||
revision: 1
|
||
source_memory_ids: []
|
||
source_checkpoint_ids: []
|
||
source_file_ids: []
|
||
source_git_commit: null
|
||
source_git_commits: []
|
||
source_agent_sync_ids: []
|
||
model_connection: Sub2API
|
||
model_name: git-restore
|
||
source_count: 20
|
||
source_revisions:
|
||
memory:41e5bdb5-a67b-49bc-b8a6-ab20b4c66fca: '1'
|
||
memory:6bb35bdc-e44f-4b8e-af69-b82961cd7c6c: '1'
|
||
memory:b3fc5d7e-f1d7-4a63-860b-37f9f35cb136: '1'
|
||
source_dispositions:
|
||
processed: 20
|
||
unchanged: 0
|
||
unsupported: 0
|
||
skipped: 0
|
||
cited_source_ids:
|
||
- curated_baseline:08fb4703-1527-4983-bb8e-e4ca735e4316
|
||
- global_guidance_memory:bf88c265-4749-4c50-85bc-4bae25298cd5
|
||
- global_guidance_memory:3f91189b-11a1-45bb-8357-4f413dc1609d
|
||
- global_guidance_memory:105b328f-4bda-4641-90a7-7282ef156316
|
||
- global_guidance_memory:5ed86f53-b53e-4534-8e51-d3a010069d5e
|
||
- global_guidance_memory:ff34c6eb-6bba-41e5-9e43-ff80941fa823
|
||
- memory:41e5bdb5-a67b-49bc-b8a6-ab20b4c66fca
|
||
- memory:6bb35bdc-e44f-4b8e-af69-b82961cd7c6c
|
||
- memory:b3fc5d7e-f1d7-4a63-860b-37f9f35cb136
|
||
- global_guidance_document:d3a20d44-6001-4c88-8772-65dbfac75e6e
|
||
- global_guidance_document:e4fc35f2-1606-4b79-9c1e-367edeea97d0
|
||
- global_guidance_document:2b47472d-3ac2-4394-8646-c6bf1c0fc270
|
||
- global_guidance_document:6973450e-6ecc-48e3-8cdd-4d7d7707d843
|
||
job_cited_source_ids:
|
||
- curated_baseline:08fb4703-1527-4983-bb8e-e4ca735e4316
|
||
conflicts: []
|
||
supersedes: []
|
||
preferences: []
|
||
source_cursor: 0
|
||
source_hash: cd96d5b27b5d1ef34ff30350e40c12b9d9b7e389c5813755521578d1f2597d9c
|
||
prompt_version: 2026-08-12.3
|
||
schema_version: '3'
|
||
curation_job_id: null
|
||
created_at: '2026-08-08T09:52:21.764309+00:00'
|
||
updated_at: '2026-09-23T15:13:04.924663+00:00'
|
||
tags:
|
||
- decisions
|
||
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
|
||
---
|
||
|
||
# 决策记录
|
||
|
||
## 1. 生产级 MCP JSON 序列化
|
||
- **决策**：`memrelay://capabilities` 含 `datetime`、`UUID` 或 Pydantic 对象时，必须先使用 FastAPI `jsonable_encoder` 再进行 JSON 编码，以避免生产环境序列化错误。
|
||
- **验证**：回归测试使用真实时间字段，并通过 Streamable HTTP MCP 验证资源输出与 `capabilities_get` 一致。
|
||
|
||
## 2. 密码库读取性能优化
|
||
- **决策**：VaultService 引入进程内 Bitwarden 条目快照（启动、手动同步、周期同步刷新），列表、搜索、详情、密码读取与唯一匹配读取均走快照；写入操作即时更新快照；TOTP 仍实时调用 CLI。
|
||
- **结果**：ARM64 列表响应时间降至约 420‑431 ms。
|
||
|
||
## 3. 会话 Cookie `Secure` 标记动态化
|
||
- **决策**：管理端同时支持局域网 HTTP 与公网 HTTPS；Cookie `Secure` 标记依据当前请求协议动态决定（HTTPS 设置，HTTP 清除），解决 HTTPS 后局域网 HTTP 会话失效的问题。
|
||
|
||
## 4. 代理缓存策略
|
||
- **决策**：OpenResty 对登录、API、MCP、密码库、上传下载及签名地址不启用代理缓存；静态资源使用 ETag 与浏览器缓存。
|
||
|
||
## 5. ARM64 构建迁移方案
|
||
- **决策**：提供可选构建时代理与 Debian 镜像参数以加速依赖下载（不改变默认/运行时网络）。
|
||
- **其他**：Windows `tar` 的符号链接问题通过 Linux 容器只读挂载方式解决；首次迁移启动延迟通过保留一致性备份并待容器恢复健康后再验证。
|
||
|
||
## 6. 数据库迁移与 UI 统一
|
||
- **决策**：数据库迁移 `20260805_0010` 在 `mcp_tokens` 表加入 `all_profiles`，支持全档案 Token 自动覆盖后续创建的使用档案。
|
||
- **UI 改动**：删除独立进度页，检查点统一在项目开发时间线管理并支持删除；操作语义统一为项目“停用/永久删除”，记忆“移入回收站”。
|
||
|
||
**来源**: `curated_baseline:08fb4703-1527-4983-bb8e-e4ca735e4316` |