AI阐微 v1.0

一、项目概况

AI阐微 是一个运行在微信公众号上的「AI 语义解析智能体 · 易经科学解卦系统」。用户通过公众号发一条消息描述自己的困惑，系统调用 DeepSeek 等大模型进行六维语义分析，生成包含卦象、卦名、文化卡、白话解读、洞察、结论等模块的完整 HTML 报告，推送到用户的微信聊天中。

项目始于 2026 年 5 月中旬，至 6 月 3 日标记 v1.0.4，历时约 3 周完成第一个可上线的生产版本。后两周（5月28日～6月3日）纳入 Git 管理，产生 113 次提交，形成 4 个 tag 版本。

二、核心数据一览

三、系统架构

3.1 整体架构

3.2 六云函数职责

3.3 数据流：从用户发消息到收到报告

1. 用户发消息 → 微信服务器 → webhook（POST XML）
2. webhook 验签 → 解析 → 状态机路由（IDLE 检测触发词 / Q1～Q6 收集信息）
3. webhook 将请求写入 report_tasks 集合 → 5s 内回复微信（不可超时）
4. task-queue（10s 轮询）拉起新任务 → HTTP POST 到 analyze
5. analyze 调用 DeepSeek API（含 3 次降级 4→Kimi→Claude）→ 执行 22 项质检 → 程序化 HTML 装配 → 上传 COS
6. analyze 更新 reports 集合 → 通过客服消息推送卡片链接给用户
7. 用户点击卡片 → report.html（COS CDN）→ 加载报告（非付费用户看预览）
8. 付费流程 → api 获取支付参数 → payment 统一下单 → 微信支付 → 回调通知 → 解锁报告

四、技术实现要点

4.1 LLM 驱动的内容生成流水线

项目最核心的技术挑战：让 LLM 稳定产出结构正确的易经报告 HTML。

• SKILL.md 设计：一份 300+ 行的结构化技能文档，定义了完整的执行步骤（输入处理→语义解构→起卦→四层解读→HTML 装配），作为 system prompt 注入给 DeepSeek
• 22 项质检体系：涵盖卦名正确性、六爻阴阳数量、之卦推导、模块完整性、SVG 有效、无非法标签等。检测到问题后构造 retry prompt 让 LLM 自我修复，最多重试 2 次
• 程序化 HTML 装配：LLM 按 Markdown 块格式输出结构化内容 → 代码解析成 6 个区块（hero/culture_card/user_statement/baihua/insight/conclusion）→ 程序化拼装最终 HTML。避免了 LLM 直接输出 HTML 的不稳定性
• 降级链：DeepSeek v4 Flash → Kimi → Claude，前一个失败/超时自动切换，确保服务不中断

4.2 微信生态集成

• 消息入口：微信 XML 消息签名验证、文本/事件/菜单多类型路由
• OAuth 静默授权：用户点击卡片后自动获取 openid，localStorage 缓存减少重复授权
• 客服消息推送：报告生成完成后主动推送到微信聊天
• JSAPI 支付：统一下单 → 调起支付 → 异步验签回调 → 通知用户
• 管理后台：微信扫码登录（PC）/ 静默 OAuth（微信内），在线改价、数据统计

4.3 对话状态机设计

从最初的 9 个状态（IDLE / DIVINATION_SELECT / SMART_CONFIRM / Q1～Q6 / POST_REPORT / HISTORY / PROCESSING / DONE）逐步精简到 6 个：

• 删除 POST_REPORT：追问 LLM 回答质量不高，不如回落 IDLE 重新起卦
• 删除 HISTORY：文本版历史查询体验差，由前端 history.html 替代
• DONE → IDLE：完成态下任何消息直接回落，简化竞态处理
• SMART 智能模式：LLM 驱动的对话替代硬编码状态机，在收敛速度与对话质量之间调参
• TTL 兜底：5 分钟无交互自动回 IDLE，防止状态残留

4.4 卡片分享系统

"保存卡片"功能是 v1.0 后期最重的开发任务，经历了多次架构反复：html2canvas → 独立 card.html → 原生 Canvas → 内嵌 history.html。最终方案是在 history.html 内用 Canvas 2D API 绘制 600×900 PNG：

• Canvas 直接绘制：完全绕过 html2canvas 在 X5 WebView 下的兼容性问题
• 手动曲线绘制：微信 X5 不支持 roundRect 和 letterSpacing，全部用 arcTo 和逐字定位替代
• 布局协调：Hero 意境区（220px）、卦名图标区（80px）、洞察文字区（动态高度，上限 80 字）、品牌区（～100px）、QR 码（144×144）共 6 层，像素级对齐防止重叠
• QR 码：使用 qrcode.js 生成 base64，drawImage 嵌入 Canvas
• 洞察提取：付费报告的洞察内容从 COS HTML 中 regex 提取，非付费用替代文本
• 交叉验证：像素采样（getImageData）结合源代码 regex 双重确认生成结果

卡片生成功能的迭代过程本身就是一个缩影，反映了项目中反复出现的挑战：

4.5 数据库配额红线下的架构设计

CloudBase 体验版每月读写配额各 50,000 次，这条红线深刻影响了架构设计：

• 所有数据库查询必须带 .limit(N)，禁止无限制 .get()
• task-queue 每 10s 轮询是最大消耗源（月耗 ～18,900 次），轮询间隔不可随意减小
• 大容量导出任务（如基线备份）使用 offset 分页，每次 100 条
• conv_state 用 TTL 自动过期清理，避免无用数据堆积

五、工程方法与纪律

5.1 七条工程原则（来自全局 CLAUDE.md）

这些原则在 v1.0 开发过程中逐步沉淀，最终成为所有项目共享的工程纪律：

5.2 基线备份体系

一套完整的灾备方案，按场景分为两种：

• 本地版本基线：robocopy 简单快照，开发中随时打点
• 线上生产版本基线（八步备份法）：
  1. 复制工作目录
  2. 下载 COS 前端文件（report.html / history.html / admin/index.html）
  3. 函数代码 zip（含 node_modules）
  4. 函数配置（超时/内存/触发器）
  5. 环境变量（密钥明文）
  6. 数据库 6 个 collections 导出
  7. 持久记忆 / CLAUDE.md / plan / skill 备份
  8. 自动完整性校验 + README 灾备恢复手册

5.3 版本管理与 Tag 策略

Git 在 5 月 28 日才初始化，113 次提交全部发生在 7 天内。版本标签语义清晰：

• v1.0.1：工程基建 + 报告架构重构（MD 解析 + 程序化 HTML 装配）
• v1.0.2：智能模式 + 状态机简化 + 数据库查询优化
• v1.0.3：SVG 包皮剥离 + 提示文本统一 + 冷启动优化 + 部署脚本
• v1.0.4：卡片分享系统 + 图钉装饰

部署纪律："部署完成 = 提交完成"。每次 node scripts/deploy-*.js 成功后立即 git add + commit，不累积、不合并。66 个脚本中 deploy-* 和 rollback-* 是日常主力。

六、人机协作经验

6.1 协作模式演变

6.2 高效模式

6.3 关键教训

6.4 用户画像与工作风格

用户（任老师）在 v1.0 开发中展现出的特征深刻影响了协作模式：

• 极高的质量标准：像素级校对，不放过任何"差不多"。卡片 QR 码反复调整 1px 级别的偏移
• 强劲的追问能力：发现不一致时能一路追问到底，直到根因水落石出
• 红线意识："没有我说可以，你都不得修改" — 对越界行为零容忍
• 工程纪律感：每次部署前要 checklist、打基线、准备回滚。这是专业运维思维
• 直接的情绪表达：不满意时直白表达（包括激烈措辞），满意时简洁肯定
• 知识储备：对易经有深入了解，能识别 LLM 输出的卦象错误；有运维经验，理解部署风险

这种协作风格对 AI 的要求是：先确认后执行、精确到像素、不投机取巧、不能有"凑合用"的思维。

七、从 Git 历史看开发节奏

113 次提交的时序分布清晰地反映了 v1.0 冲刺阶段的开发特征：

7.1 按日期分布

7.2 提交信息词频

提交信息的压倒性主题是 fix — 超过 45% 的提交是修复。这符合 v1.0 冲刺的特征：快速出功能、即时修 bug。典型模式是"feat 出一个功能 → 连续 n 个 fix 修到满意"。

八、项目特点

AI阐微 v1.0 的开发呈现几个显著特点：

• 全栈 AI 生成：从系统架构到每一行代码，全部由 Claude 生成。人类负责需求定义、质量把关、决策判断、部署操作。
• 微信生态的高复杂度：XML 消息、验签、OAuth、JSAPI 支付、客服消息、X5 WebView 兼容性——每个环节都有细节陷阱。
• 知识密集型领域：易经的卦象结构（本卦/之卦/互卦、六爻、世应、卦德、五行生克）需要精确建模，LLM 的幻觉输出必须被质检体系捕获。
• 资源约束下的架构：CloudBase 体验版的 5 万次/月配额红线驱动了轻量级队列、分页查询、TTL 清理等架构决策。
• 高密度迭代：7 天 113 次提交，平均每天 16 次。v1.0 冲刺阶段需求变化极快，要求工程体系既能保障速度又能守住质量底线。
• 无 UI 框架的前端：report.html 和 history.html 都是纯手写 HTML/CSS/JS，没有 React/Vue，没有构建工具。直接上传 COS 即可部署。

九、展望

v1.0 完成了从 0 到 1 的跨越。回顾整个开发过程，可以清晰地看到几个值得持续改进的方向：

• 测试覆盖面的扩大：卡片 Canvas 绘制没有测试是明显的缺口。Canvas 的像素级测试虽然实现成本高，但可以减少"肉眼校对→微调→再提交"的重复循环。
• LLM 输出的可预测性：22 项质检 + 最多 2 次 retry 已经工作了，但能否进一步降低 retry 率？可能需要更精细的 prompt 工程或更结构化的输出约束。
• 前端工具链：纯手写 HTML/CSS/JS 在初期够用，但卡片 Canvas 的布局调试暴露了缺乏工具支持的痛点。不过考虑到微信 X5 的兼容性限制，引入构建工具需要谨慎评估。
• 基线自动化：八步备份法已经较为完善，但执行仍需人工触发。如果能在部署前自动触发基线、在部署后自动验证一致性，安全网会更密。
• 并发与配额：自适应并发算法从 MAX_C=5 提升到 30 后效果如何？需要更多线上数据来调优。同时 CloudBase 配额耗尽时的降级策略需要更明确。

十、传统开发 vs AI Coding：效率对比

用 费米估算法 逐模块估算：如果这个项目按传统手工开发（不使用 AI Coding），需要多少人力。以下是 13 个模块的详细估算。

10.1 逐模块估算明细