| 维度 | Cursor | Opus | Codex | GPT | DeepSeek | 平均 | 自评 | 偏差 |
|---|---|---|---|---|---|---|---|---|
| 文档质量 | 8.2 | 7.0 | 8.0 | 7.0 | 8.5 | 7.7 | — | — |
| 代码架构 | 6.4 | 5.0 | 5.5 | 5.5 | 4.5 | 5.4 | 7 | -1.6 |
| MCP 实现 | 8.0 | 7.0 | 7.0 | 6.8 | 7.0 | 7.2 | — | — |
| 测试质量 | 7.6 | 7.0 | 8.2 | 7.2 | 6.0 | 7.2 | 7 | 准确 |
| 安全隐私 | 7.1 | 7.0 | 6.0 | 6.4 | 5.0 | 6.3 | 8 | -1.7 |
| 产品定位 | 7.2 | 5.0 | 7.6 | 7.5 | 8.0 | 7.1 | 7 | 准确 |
| 综合 | 7.3 | 6.5 | 7.1 | 7.0 | 6.4 | 6.9 | 7.5 | -0.6 |
五家评测共提出 32 项独立问题/建议，按结论分类统计：
理由：全票一致。单文件承载 CRUD + 搜索 + 冲突检测 + 上下文生成 + HTML 页面 + 导入导出 + 迁移，违反单一职责。外部贡献者和 AI 修改代码的回归成本持续上升。
方案：拆为 8 模块（storage / retrieval / conflicts / context / reconcile / reports / compat / facade），无行为变化，每拆一块 327 测试全绿。
21 处 print(..., file=sys.stderr) 是 Python 反模式。MCP stdio server 裸写 stderr 有协议污染风险。伴随拆分同步完成。
表现层逻辑（HTML+CSS+JS f-string 拼接）在核心类里是最明显的 code smell。归入 reports.py 拆分阶段。
"10.0" < "2.0" 在字符串比较中为 true。当前版本 "2.0" 短期无风险，storage.py 拆分时顺手修复。
当前 dict + 327 测试维持住了。Pydantic 会增加核心依赖（当前仅 mcp + portalocker），违反轻量级定位。拆分完成后再评估。
对单一维护者够用。等有第二个贡献者或 MCP 层统一返回值后一起引入。
常量已集中在 core.py 顶部 50 行。拆分后常量自然跟随模块（如 SEARCH_RELEVANCE_THRESHOLD 进 retrieval.py），不需要额外间接层。
具体的代码 bug 断言，需实际检查。如属实则立即修复。
安全文档把自己的加密原语说错，对主打隐私的项目是致命的信任伤害。
用户设了密钥以为安全，实际明文存储——"最危险的安全反模式"。应改为 raise RuntimeError 拒绝启动。
auth_header[7:] != self.token 存在 timing attack 面。改用 secrets.compare_digest，一行修复。
提升到 600k 轮（OWASP 建议）。不引入 Argon2（避免新依赖）。用 enc:v2: 前缀处理兼容迁移。
改为三层表述：(1) Core: 零网络 (2) Reader: 仅 localhost (3) SSE: 可选自托管+TLS
默认限制为 ~/.engram/ 子目录；超出范围返回警告但不硬拒绝（本地信任模型）。
SSE 模式 host ≠ 127.0.0.1 且无 token 时，拒绝启动。CORS 默认限制为 localhost。
Profile 是唯一含 PII 的地方。Lessons/decisions 本身就是要注入给 AI 的，过滤会损害核心价值。
当前 enc:v1: 前缀已预留版本化空间。升级时用 enc:v2: 标记，解密按前缀选参数。
Engram 是个人开发者工具，不是企业安全基础设施。HSM 完全超出目标用户场景。
用 FastMCP 支持的 Python type hints 替代字符串参数。先改 Tier-1 的 10 个工具，再改 Tier-2。
成功时 JSON 结构化；错误保持自然语言（LLM 理解更好），但包一层 {"ok": false, "error": "..."}。不做完整 envelope。
MCP 规范正确。但 FastMCP 对 Resources 的 LLM 集成不够成熟，Claude Code/Cursor 体验不统一。等生态成熟后迁移。
Tier-1 默认 10 个已解决核心问题。不大幅合并（损失语义清晰度），但给 Tier-2 加分组标签和 "When NOT to use" 指引。
core / all 两档覆盖 95% 场景。等用户反馈后再加细分。
先在 docstring 补充行为说明，后续 MCP 规范支持时正式标注。
当前唯一方案。Pin FastMCP 版本，等公开 API 后迁移。
注释写 "Keep all tools by default" 但默认值是 "core"。一行修复。
新增 test_mcp_tools.py，覆盖 Tier-1 全部 + Tier-2 高频 5 个。
新增 test_mcp_e2e.py：子进程启动 server → list_tools → 调用核心工具 → 验证返回。
先加覆盖率报告（不设门禁），拆分完成后再设阈值。
单用户单进程场景，portalocker 已保证互斥。不是当前真实场景。
补充：错误密钥、损坏密文、cryptography 缺失、PBKDF2 升级兼容。
reports.py 拆分后补充 XSS payload fixture。
设计为独立脚本（需 API key）。可加为 nightly 可选 job。
core.py 拆分完成后再写（否则写完就过时了）。
信息有价值，但核心差异不在检索性能而在跨工具身份共享。在竞品对比中加入 OMEGA 等，明确差异点。
200 条规模够用。短期不加向量检索（避免重依赖），中期提供 embedding hook 接口。
录制 60 秒跨工具 demo，嵌入 README 首屏。
主文只保留"多工具 AI coding power users"，其他 persona 收入折叠区。
短期 README 解释清楚，长期评估是否迁移。
Round 10 D4 测试完成后作为 README badge。
根因：犯了"实现了就以为安全了"的认知错误。
教训：安全评估必须同时检查"做了什么"、"说了什么"（文档）、"没做什么"（失效路径）、"说过头了什么"（营销口径）。
根因：典型的"专家盲区"——作者对 4277 行文件的心智地图完整，感觉"结构清晰"。外部评测者（模拟新贡献者）普遍感到不可维护。
教训：架构评估必须从"陌生人能否在 30 分钟内理解并安全修改"的角度出发。
Opus 给 5 分（赛道拥挤），其他四家给 7.2-8.0。Opus 做了最深的竞品扫描，发现了我们不知道的竞品。
教训：叙事自洽 ≠ 市场安全。需要持续监控竞品动态。
| # | 任务 | 问题 | 复杂度 |
|---|---|---|---|
| 1 | SECURITY.md: Fernet → AES-256-GCM | I | 低 |
| 2 | 加密静默失效 → raise RuntimeError | J | 低 |
| 3 | SSE token → secrets.compare_digest | K | 低 |
| 4 | _apply_tool_tier 注释修正 | Z | 低 |
| 5 | README FAQ 安装路径统一 | AH | 低 |
| 6 | README 加 ENGRAM_TOOLS 说明 | AI | 低 |
| 7 | README stale days 90 → 30 | AJ | 低 |
| 8 | "100% local" 叙事精确化 | M | 中 |
| 9 | "automatically" 措辞修正 | AM | 低 |
| 10 | SSE 安全加固（CORS + 无 token 警告） | O | 中 |
| 11 | 验证 sys 导入问题 | H | 低 |
| 阶段 | 拆出模块 | 预估行数 | 依赖 |
|---|---|---|---|
| 2a | storage.py | ~200 | 无 |
| 2b | retrieval.py + conflicts.py | ~400 | storage |
| 2c | reports.py | ~500 | storage |
| 2d | reconcile.py | ~400 | storage |
| 2e | context.py | ~200 | retrieval, storage |
| 2f | compat.py | ~300 | storage |
伴随完成：print→logging / schema 版本比较 / PBKDF2 600k 升级
| # | 任务 | 问题 |
|---|---|---|
| 1 | test_mcp_tools.py: Tier-1 全部 + Tier-2 高频 | AA |
| 2 | test_mcp_e2e.py: stdio 冒烟测试 | AB |
| 3 | test_crypto.py 扩展到 20+ | AE |
| 4 | *_json 参数结构化（Tier-1 先行） | S |
| 5 | 返回值半结构化 | T |
| 6 | 路径参数校验 | N |
| 7 | 覆盖率报告 | AC |
| # | 任务 | 问题 |
|---|---|---|
| 1 | 录制 60 秒跨工具 demo GIF | AP |
| 2 | README ICP 收窄 | AQ |
| 3 | "身份层"可检验定义 | AS |
| 4 | 竞品对比加入 OMEGA 等 | AN |
| 5 | piia-engram 品牌解释 | AR |
| 6 | docs/architecture.md | AK |
| 评测者 | 评测方式 | 特点 | 最有价值发现 |
|---|---|---|---|
| Cursor 2.5 | 静态阅读 | 最友好 | generate_context 副作用 |
| Opus 4.7 | clone + 跑测试 + 覆盖率 | 最严格 | OMEGA 竞品、38% 覆盖率、timing attack |
| Codex 5.5 | clone + 跑测试 | 最实操 | 拆分顺序、MCP 契约文档 |
| GPT Pro | 静态 + MCP 规范 | 最合规 | MCP Resources、sys bug、KDF 参数 |
| DeepSeek | 静态阅读 | 最关注安全 | 加密静默失效、CORS 风险 |