TECHNICAL • REPORT

AI阐微 v1.0

项目经验与教训总结报告

在微信生态上构建
AI 语义解析智能体 · 易经科学解卦系统

扫码阅读全文

一、项目概况

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

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

核心定位：AI（DeepSeek）+ 传统文化（易经）+ 微信生态（服务号）的三位一体产品。
技术栈：腾讯云 SCF（Node.js 18）+ CloudBase MongoDB + COS 对象存储 + DeepSeek API + 微信公众平台。

二、核心数据一览

云函数

部署脚本

测试文件

113

Git 提交

版本 tag

～5.7k

shared 代码行

～2k

核心代码行

7 天

Git 追踪周期

9→6

状态机缩减

～80

卡片迭代次数

5k+

会话消息数

3 轮

LLM 降级链

分支（master）

三、系统架构

3.1 整体架构

3.2 六云函数职责

函数	超时/内存	职责
webhook	10s / 256MB	微信消息入口。验签、XML 解析、对话状态机（IDLE→Q1～Q6→PROCESSING→DONE）、写任务队列
task-queue	600s / 256MB	每 10s 轮询 report_tasks，HTTP POST 调 analyze，自适应并发 1～30，死信检测
analyze	600s / 512MB	(1) SKILL.md 引导 LLM 生成报告 (2) 22 项质检 (3) 程序化 HTML 装配 (4) COS 上传
api	30s / 256MB	报告查询/列表/内容代理/用户同步/管理后台/数据统计，内容锁定预览
payment	30s / 256MB	微信 JSAPI 统一下单、支付回调验签与通知、价格动态读取
keepwarm	3s / 64MB	每 5 分钟定时触发，防止冷启动影响用户体验

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

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

关键设计决策：webhook 必须在 5s 内回复微信，因此所有耗时操作（LLM 调用、HTML 生成、COS 上传）都通过 report_tasks 队列异步执行，webhook 仅做消息路由和状态持久化。

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 双重确认生成结果

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

fc9b879 feat: 保存卡片 — 点击生成 600×900 分享卡片（首次尝试） 7df7013 fix: 卡片 SVG 改用 data URL 避免 html2canvas 跨域问题 3d5b6ce fix: 卡片改用原生 Canvas，彻底解决 html2canvas 兼容 5e4be49 fix: 保存卡片改为打开 card.html 独立页面 291e3c5 feat: 卡片图片生成 — 独立 card-gen.html，Canvas 绘制 5582932 feat: 保存卡片 — history.html 内 canvas 绘制 428099c fix: 卦名空白 + 品牌重复绘制 — 卡片生成失败根因 ... b749833 feat: 保存卡片 — 仅用 Edit 工具，不外挂脚本 ... 1c03979 v1.0.4 feat: 右上角图钉 📌

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

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

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

五、工程方法与纪律

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

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

原则	在 v1.0 中的实践
先澄清需求	每次改造前先出 plan（HTML + Mermaid 流程图），用户确认后再动手
拆分细化	所有 plan 分解为 Step 0～N，每步独立可验证。如状态机简化 plan 分 3 步：测试→改代码→部署
测试驱动	10 个测试文件覆盖：webhook 队列、analyze 回归、MD 解析、渲染、重试逻辑、智能模式等
回滚配套	每次部署前准备 rollback 脚本 + tag 标记。delete-function 被禁止，统一用 UpdateFunctionCode 保留触发器
步进交付	部署三步：node --check → 跑测试 → 部署。走一步确认一步
生产安全	构建基线（八步备份法）→干涉性检查→版本一致性检查→再部署。不改没碰过的代码
Double check	所有信息交叉验证：线上 vs 本地版本比对、基线完整性自动检查、卡片像素采样+源代码双重确认

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 灾备恢复手册

实践效果：卡片开发过程中多次出现"改坏了用户无法展示"，依靠 baseline 快速定位差异；函数部署时发现环境变量与脚本不一致，通过基线备份比对及时纠正。

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 协作模式演变

Phase 1

探索期 无结构化协作 — 用户给出模糊目标，AI 自由尝试。效果不稳定，多次产生废代码。特点是来回反复多，方向频繁调整。

Phase 2

规范期 Plan → Do → Review 循环 — 形成标准化工作流：

EnterPlanMode 出 plan（HTML + Mermaid 流程图 + 干涉性检查 + 防御措施）
用户审阅 → 确认或打回
按 Step 执行，每步验证
部署前打基线，部署后验证巡查

Phase 3

纪律化 自动化纪律机制 — 沉淀在 CLAUDE.md 的强制约束：

"没有我说可以，你都不得修改" — 红线原则
部署前 checklist（回滚就绪 / 本地测试 / 顺序 / 基线）
每次部署后立即 commit
禁止 DeleteFunction

Phase 4

高压期 v1.0 冲刺 — 高密度、高精度的 bug 修复。用户"像素级"校对卡片布局（QR 码反复移动 1px、标签行距调整），AI 必须适应毫厘必较的工作风格。

6.2 高效模式

✅ 生效的做法

格式化 CLAUDE.md：把协作纪律写进配置文件，每次会话自动加载
Plan HTML 模板：标准化流程（Context → 方案 → 干涉性检查 → Steps → 防御 → 工程原则对照 → Double Check）
/loop 压力测试：一次跑 20 遍验证稳定性
基线兜底：改动前快照，出问题快速定位差异
Tag 锚点：可执行版本标记，回滚位置明确
Double Check：所有信息交叉验证后再行动

❌ 无效/有害的做法

不写 CLAUDE.md：每次会话丢失上下文，重复犯错
无 plan 直接写代码：方向错了，改来改去浪费大量时间
热部署不同步本地：导致本地与线上不一致，基线也无法覆盖
Python/Node 脚本改源码：中文编码问题连续 8 次导致页面崩溃
html2canvas：微信 X5 不支持，花了 4 次迭代才彻底放弃
TDD 缺失的区域：卡片 Canvas 没有测试，全靠目测，效率低

6.3 关键教训

教训一：先想清楚再动手。
卡片分享功能就是最典型的例子 — 先后尝试了 html2canvas、独立 card.html、card-gen.html、内嵌 canvas、独立 card-gen.html、再回到 history.html canvas。6 次架构反复，根源是没有想清楚 X5 的限制就动手了。如果先调研微信 X5 不支持什么（roundRect、letterSpacing、html2canvas），可以一次走对。

教训二：不要绕过工具链。
用 Python / Node 脚本批量修改 HTML 源码，8 次中有 8 次因为编码问题导致页面崩溃。正确做法是只用 Edit 工具逐项修改（最终也确实这样走通了）。这个教训反复出现直到被写入红线。

教训三：CSS 像素不是 Canvas 像素。
卡片坐标反复调整了 30+ 次提交，从 insight 下移/QR 上移到最终的精密级协调。原因是初期用 demo 375px×562px 的比例直接缩放 1.6x 到 600×900，忽略了 text 实际渲染的差异。最终靠逐坐标域的独立调优才解决。

成功经验一：状态机简化。
删除 POST_REPORT（追问）和 HISTORY（历史查询）两个状态，DONE 直回 IDLE，删～200 行代码，增～5 行。干涉性分析表明不影响任何其他函数，部署后零问题。这是"少即是多"的典范。

成功经验二：程序化 HTML 装配。
让 LLM 输出结构化 Markdown 而非直接输出 HTML，代码再逐块装配，极大提升报告稳定性。配合 22 项质检和最多 2 次 retry，LLM 输出的不稳定性被有效控制。

成功经验三：步进部署纪律。
部署前 checklist（回滚脚本 / 本地测试 / 部署顺序 / 基线）加上部署后立即 commit 的纪律，使 20+ 次部署中从未出现不可恢复的生产事故。

6.4 用户画像与工作风格

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

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

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

七、从 Git 历史看开发节奏

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

7.1 按日期分布

日期	提交数	主要内容
5-28	7	Git 初始化、CLAUDE.md 工程体系、plan 标准
5-29	7	CLAUDE.md 补充、Double check 原则、plan 目录整理
5-30	1	报告架构重构（里程碑式的 MD 解析 + 程序化 HTML）
5-31	9	文化卡、印章、SVG 标题、提示文本优化
6-01	14	智能模式、状态机简化、PROCESSING 提前持久化
6-02	19	欢迎语、菜单、SVG 包皮剥离、提示文本统一、动爻修复
6-03	55	卡片分享系统冲刺（占全部提交的 48.6%）

观察：6 月 3 日是开发强度最高的一天（55 次提交），几乎全部围绕"保存卡片"功能。从上午 11:13 第一个 feat 到下午 18:20 图钉装饰，7 小时 55 次迭代，平均每 8.5 分钟一次提交。这反映了两件事：功能复杂度高、以及初期方向反复浪费了大量时间。

7.2 提交信息词频

fix:

修复（最多）

feat:

新功能

chore:

工程/依赖

～50

fix: 类提交

提交信息的压倒性主题是 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 配额耗尽时的降级策略需要更明确。

v1.0 不是终点，而是一个可以安全迭代的起点。
7 天 113 次提交、零生产事故、4 个可执行版本 — 工程体系证明了它的价值。

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

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

10.1 逐模块估算明细

模块	工作内容	传统（人月）
webhook	微信消息验签、XML 解析、状态机（9→6 个状态）、写任务队列、智能模式 LLM 对话	0.5
analyze	DeepSeek/Kimi/Claude 降级链、22 项质检 + retry 逻辑、SKILL.md prompt 工程、程序化 HTML 装配	1.5
api	11 个 REST 接口（手动路由）、内容锁定预览、OAuth 同步、管理后台、统计	1.0
payment	JSAPI 统一下单、异步回调验签、支付状态通知、在线改价	1.0
task-queue	10s 轮询、自适应并发算法（1～30）、死信检测、超时处理	0.5
keepwarm	定时触发器，3s/64MB	0.1
report.html	响应式 H5 页面、OAuth 集成、JSAPI 支付调起、预览/付费墙、X5 兼容适配	1.0
history.html	历史记录 + 卡片 Canvas 绘制（roundRect/letterSpacing 手动 polyfill，像素级调优）	1.0
DevOps 部署	SCF 6 函数部署脚本、COS 上传、回滚脚本、环境变量管理	0.5
基线灾备	八步备份法设计实现，自动完整性校验，灾备恢复手册	0.5
微信接入	服务号配置、菜单设置、客服消息、OAuth 域名备案、JSAPI 支付资质与沙箱	0.8
测试与 QA	10 个测试文件、22 项质检调参、WeChat 全流程回归、X5 兼容性测试	1.0
架构与管理	架构设计、需求澄清、跨模块联调、bug 追踪、重构决策	1.0
合计		10 ～ 11

前提说明：微信接入的"资质门槛"（备案、支付资质申请）无法被 AI 加速，传统和 AI 都要花一样的时间。调试类工作（X5 兼容性、像素级对齐）AI 不会一次性走对，但迭代速度远快于人工。

补充说明：以上估算仅涵盖开发与运维角色（后端/前端/DevOps），未计入传统开发中必要的其他角色：产品经理（需求梳理与验收）、领域专家（易经知识培训与审核）、平面设计师（品牌视觉、卡片 UI 设计）。这些角色在 AI Coding 模式下或由任老师一人兼任，或由 AI 直接承担（如视觉设计），但在传统开发中是不可或缺的独立角色。加计这些角色后，传统开发的实际人力成本会更高。

关键结论：3 周完成传统约 10 个月的工作量，效率提升约 13～15 倍。但这建立在"人负责判断、AI 负责执行"的分工前提上——架构决策、需求定义、质量把关仍完全取决于人的判断力，AI 没有取代人的角色，而是极大地压缩了执行层的周期。