本文以第一人称视角记录 2026-02-15 至 2026-02-21 期间，在 easy_encryption_tool（EET）项目上的 Vibecoding 实践与思考，涵盖产品设计、架构策略、用户体验与安全合规等方面。这既是一份阶段复盘，也是一份面向未来迭代的设计决策备忘录。

一、为什么写这份文档

这一周，我持续通过 Vibecoding 的方式迭代 EET。 几乎每次与 AI 协作完成一个功能或修复一个问题，都会产生新的设计想法。但这些想法往往散落在对话、commit message 与临时记录中，缺乏系统沉淀。

因此，我希望把这些思考整理为一份结构化文档：

  • 对本周工作的复盘
  • 对关键设计决策的记录
  • 为未来演进提供可追溯的设计上下文

这不仅是总结，更是让项目持续演进的“认知基础设施”。

二、产品与功能层面的思考

2.1 国密与国际算法的统一入口

QQ_1771657030334

EET 最初支持的是国际算法（AES、RSA、ECC、HMAC）。 问题在于：如何在不破坏既有体验的前提下，引入 SM2、SM3、SM4、ZUC 等国密算法？

我的结论是：

算法可以不同，交互必须一致

因此我坚持：

  • 所有算法共享统一参数风格
  • -i 输入、-e base64、-f 文件、-o 输出保持一致
  • 国密命令与 AES/RSA 命令保持完全对称

这样用户从 AES 切换到 SM4 时，不需要重新学习工具。

国密能力通过可选依赖提供，未安装时给出明确提示，而不是让用户自行排查环境问题。 这是产品决策，而不是实现细节。

2.2 输出规范必须结构化

QQ_1771657080284

CLI 工具最容易被忽视的问题，是输出格式的不一致。

如果输出风格混乱：

  • 无法稳定脚本化
  • 难以进入管道处理
  • 无法对接系统与日志平台

因此我设计了一套严格的输出结构：

metadata

记录操作类型、算法、编码与输入来源 不包含敏感数据 支持未来扩展（kid、aad、envelope、compliance tags 等）

result

仅包含原始密码学输出 无装饰、无标签、无格式化 保证可复制、可复用

runtime

记录 request_id、timestamp、duration_ms 为审计、追踪、SIEM 接入提供基础

这套结构本质上是：

让 CLI 输出天然具备 API 语义

未来扩展字段时无需破坏兼容性，这是长期演进的关键。

2.3 与 CipherHUB 的兼容是产品原则

EET 与 CipherHUB 并不是两个独立项目，而是同一体系的不同入口。

因此我要求：

  • 默认密钥逻辑一致
  • IV 与 GCM AAD 处理一致
  • padding 规则一致

这样用户可以：

  • 在网页加密 → CLI 解密
  • 在 CLI 加密 → 网页验证

这不是技术优化，而是产品边界设计。

三、架构与设计思考

3.1 明确三层职责

我坚持将系统拆分为三层：

  1. 加密逻辑层：只负责密码学运算
  2. 输出构建层：组装 metadata / result / runtime
  3. 渲染层：负责 pretty / json / raw 等展示方式

这样：

  • 改输出不会动密码学代码
  • 改密码学实现不会影响输出协议

output_builder 与 output_renderer 的存在，就是为了守住这个边界。

3.2 公共逻辑必须集中

重复代码意味着未来维护成本指数增长。

因此我把通用逻辑抽离：

  • key/IV 处理 → common.process_key_iv()
  • 参数互斥校验 → validators.py
  • 用户提示与修复建议 → hints.py

每个命令模块只关注自身职责， 公共逻辑集中维护，演进更可控。

3.3 智能提示的取舍

我曾尝试：

  • 自动补全
  • 命令纠错
  • 参数示例提示
  • 启动欢迎面板

但实践证明：

  • 自动补全在部分环境下存在兼容问题
  • 复杂提示系统维护成本较高

最终保留：

  • 无子命令时的引导面板
  • 相似命令建议
  • 参数错误示例

因为这些：

用户价值高，系统复杂度低

这是一个典型的工程取舍。

3.4 可扩展性必须预留

在 metadata 与 runtime 设计时，我刻意留出扩展空间：

metadata 未来可加入：

  • kid
  • envelope 信息
  • 签名算法套件
  • 合规标签

runtime 可接入：

  • tracing id
  • 分布式 request id
  • SIEM 日志系统

这样未来需求变化时，不需要重构协议。

四、用户体验层面的思考

4.1 CLI 输出既是 UI，也是 API

输出既要：

  • 视觉清晰
  • 结构明确
  • 可复制
  • 可脚本处理

因此我采用：

  • metadata 表格在上
  • 主结果单独分区
  • 横线分隔
  • 标签统一风格

这让 CLI 同时具备：

人类可读性 + 机器可解析性

4.2 长输出的矛盾

QQ_1771657205767

密文和签名往往很长。

  • 不换行 → 屏幕溢出
  • 硬换行 → 复制污染

最终方案：

  • 终端软换行显示
  • 原始输出不插入 \n

这样既可读，也可复制。

4.3 国际化与一致性

我统一将所有提示改为英文，原因很简单：

  • 开源工具默认面向全球
  • 文档、API、CLI 使用统一语言
  • 减少认知切换成本

一致性本身就是用户体验的一部分。

4.4 错误提示必须可行动

错误信息的目标不是描述问题，而是帮助用户修复问题。

因此：

  • base64 错误 → 给出正确示例
  • 参数冲突 → 解释语义
  • 依赖缺失 → 提供安装命令

这些提示集中在 hints.py 中统一管理。

4.5 非对称算法输出的特殊性

RSA、SM2、ECC 输出通常更长、更复杂。

因此我统一规则：

  • 元信息在上
  • 主结果独立区块
  • 去掉视觉框架
  • 便于复制

最终，对称加密、签名、哈希全部统一到同一视觉逻辑。

五、安全与合规

5.1 安全审查驱动改进

一次工程级安全审查暴露了多个问题：

  • 使用 random 生成随机数
  • 解密错误泄露私钥路径
  • 网络请求无超时

这些问题全部修复，并将审查报告转化为持续检查清单。

5.2 敏感信息零泄露

这是原则问题：

  • 默认不显示密钥或 IV
  • 解密失败不暴露私钥路径
  • verbose 模式才允许额外信息

安全不是特性，而是底线。

5.3 密码学正确性细节

细节决定可信度：

  • 使用 secrets 生成随机数
  • Base64 严格校验
  • GCM 认证失败明确提示

这些都是让工具值得信任的基础。

六、小结

这一周的 Vibecoding，本质上在推进三件事：

  • 扩展能力：国密支持、ECC 曲线完善
  • 统一规范：输出结构、参数语义、错误提示
  • 打磨体验：视觉输出、复制行为、提示系统

在架构上，我坚持分层与抽象； 在安全上，坚持零泄露原则； 在产品上，坚持一致性优先。

EET 的目标始终没有改变：

成为一个好用、可信、可扩展的 CLI 加密工具。

  • 好用：参数一致、输出清晰、提示友好
  • 可信：实现正确、安全可审计
  • 可扩展：协议稳定、能力可演进

这些原则将继续指导后续迭代。

文档生成于 2026-02-21，基于近期 Vibecoding 实践与相关设计记录整理。