案例2 AI低代码协作开发-最佳实践手册-V1

本项目无论在传统编码开发还是低代码开发场景下，都属于定制程度非常高的需求，因为不仅需要实现单一表格的数字化构建，还需要满足未来非IT人员的使用场景。

• 项目 表单管理系统（自助建表 + 审批流 + 台账打印）

• 周期 跨两个工作日 · 但实际有效投入约 4 小时

• 难点 上千份不同字段、样式表单，要求不具备开发能力的业务人员能够通过系统，自动化表单生成系统，随时创建随时修改。

目录

1. 需求与背景
2. 推进时间轴 — 七步走完全程
3. 七阶段实操 — 从素材到上线
4. 开发问题—发现到解决
5. 提问模板库—如何有效提需求
6. 检查清单 — Skill能力补充

第 1 章 需求与背景

这是一个来自真实客户需求的，

1.1 需求原话（按提出时间排列）

10-19 17:24 · 首轮需求描述（同时提供了 11 份真实表单材料）

"客户是一家做生物研发的公司，他们每个产品都会有自己的研发流程和表单需要填写，然后每个表单可能在不同研发阶段，会做调整，形成新的版本。现在公司都是通过打印表单填写的方式来做，公司为了管理合规，需要把每个表单的内容以及对应的版本，建立数字化系统来统一管理。公司大概有1000多个这样的表单，目前提供的11个表单是比较典型的。"

第一版方案就是基于这段话做的。但真正决定项目形态的内容，是第二天早上才补上的：

10-20 09:05 · 次日补充（这三条改变了项目性质）

"需要注意几个问题
1、需求设计需要考虑织信平台的开发能力。
2、客户提出，希望未来这1000份表单甚至更多的表单，是可以允许客户直接在织信的使用界面，通过导入的方式，让系统自动生成可表单以及交互界面的。不需要通过织信后台去开发。因为他们都是不懂it的业务人员。所以需要考虑如何用织信平台构建表单创建操作流程。
3、业务人员不仅需要可以创建表单，还需要可以修改表单，每次修改，表单的版本都会加1，但是不影响历史版本，历史数据会记录当时自己的表单版本，后续可追溯。"

10-20 09:06 · 范围收敛

"另外不需要考虑产品表的部分，每个表单自己单独形成一套数据链即可，不会和表单之外的关联，不同表单之间，也不存在共用的数据表"

再往后，边界是靠一轮问答敲定的。10-20 09:57，一次性回复了7个待确认问题，原样列在下表（问题原文未保留，这里只列答复）：

#	答复原文	这条定下了什么
1	"修改这个动作是由用户主动点击，然后进入修改界面的，所有修改内容一旦保存发布，都属于版本+1"	改版由用户主动发起；保存发布 = 版本 +1
2	"用户提交，具体操作流程参考答复1"	提交流程与修改流程一致
3	"放在一个应用，专门建一个分组来管理。但是这个是作为后台数据，前端用户在找不同表单的台账的时候，可能是通过一个新建的页面，有一个筛选框，可以下拉，以及检索关键字，找到对应表"	一个应用 + 一个分组当后台；前台用一个独立页面，下拉筛选 + 关键字检索找表
4	"这种创建表单的时候，需要增加一个选项，是否有审批流，有审批流程的需要提供审批流配置方案，（仅考虑简单的3-4个节点的单流程审批），没有审批流的就直接录入台账"	建表时可选"是否需要审批流"；只做 3–4 节点单流程；不选审批的直接入台账
5	"不需要电子签名"	不做电子签名6
6	"不需要补录"	不做历史补录
7	"永久保存"	数据长期保存

而第三块能力，是系统已经跑起来之后、当天下午才提出来的：

10-20 15:42 · 打印需求

"以PD02过滤器使用_台账这个表为例，如果我最终需要打印部分台账数据，最终的效果也是生成我上传的这份源文件，帮我出一个程序设计方案"

1.2 后续开发只围绕这五条展开

把上面的原话拆完，能当作开发输入的只有下面五条。列这张表的目的不是"分析需求"，而是给后面所有技术选择划一条线：能对上这五条的才做，对不上的一律不做、不猜、也不提前设计。后面每一次想加东西，先回来对照这张表。

事实	原话依据	对方案的硬约束
① 场景	每个产品有自己的研发流程和表单，表单在不同研发阶段会调整，形成新版本	表单不是"一张静态表"，而是"某个阶段的某个版本"——版本必须是一等公民
② 现状	现在都是通过打印表单填写的方式来做	不是把已有电子数据搬上来，而是要从上传的原始文件里反推出结构
③ 规模	大概 1000 多个表单，提供的 11 个是比较典型的	必须元数据驱动：新增一张表是"新增一条记录"，不能一张张配
④ 操作者	不懂 IT 的业务人员，直接在织信使用界面导入，不走后台开发	需要一条"业务界面 → 有权限的那一层 → 建表 → 发布"的跨层链路
⑤ 版本	修改即版本 +1，不影响历史版本，历史数据记录当时的表单版本	结构变更要留快照，历史记录要能绑定到"当时那一版"

1.3 需求边界是分三次扩的

有一点值得特别说明：需求不是一次说完的，而是三次、跨两个工作日才补齐。这个顺序本身有参考价值——每一次补充，都把系统的性质改了一次。

时间	补了什么	系统性质随之改变
10-19 17:24	把 1000+ 表单的内容和版本统一管起来	从"纸质"变成"表单库 + 台账"，核心是存得下、查得到
10-20 09:05	业务人员自己导入生成，不走后台开发	从"表单库"变成"表单工厂"，核心是自己会建表、会升版
10-20 15:42	打印结果必须等于上传的源文件	加上"版式还原"，核心从数据对变成输出也对

为什么第三层最难，也最关键

前两层是"把纸变成系统"，第三层是"把系统变回纸"。方向相反，难度完全不同：前两层只要数据对就行，第三层要求字体、列宽、边框、合并单元格、页眉页脚全部保持原样。

如果只做前两层，业务部门会说"系统是挺好，但我报上去的材料还得手工重打一遍"——这个系统就没有闭环。

而且第三层是系统已经跑起来之后才提的，不是一开始就写在需求里的。这提醒一件事：需求补充不可怕，可怕的是方案里没有给"以后要加一层"留位置。

1.4 核心难点：把"开发动作"改成"业务动作"

前面三层需求回答的是"想不想要"，真正决定这个项目难度的是原话里的一个数字——1000 多个表单。

按传统低代码的思路，这件事在人力上不可能完成

主流低代码平台有一个隐含前提：建表 = 开发动作。表由实施顾问或 IT 在后台搭建——建表、配字段、设类型、设必填、挂分组、配流程、再发布；业务人员只负责在里面填数据。

按 1000 份表单、每份 20–30 个字段粗算，就是 2 万到 3 万次字段配置；更麻烦的是每个表单在不同研发阶段还会改版，每改一次版本 +1，就要把配置重来一遍。这不是"工作量偏大"，而是根本无法维护——开发排期永远追不上表单改版的节奏。

所以这个项目真正要解决的，不是"怎么把表建出来"，而是：怎么把"建表"这个开发动作，变成业务人员能直接做的业务动作。两者的差别可以用一张表看清楚：

维度	按传统低代码思路	本次实际做法
操作对象	后台的表结构、字段、流程配置	一份原始的 Word 表单文件
操作者	实施顾问 / IT	业务人员（自述"不懂 IT"）
前置知识	懂字段类型、绑定关系、发布机制	会用 Word，看得懂自己那张表
新建一张表的成本	数十次配置点击 + 一次应用发布	几个动作：上传 → 核对 → 确认 → 等完成
改版的成本	找回原配置，逐项比对修改	在原始文件上改完，重传一次
谁承担维护	IT 部门，永久占用排期	业务部门自己，随改随生效

这个转变不是"再做一个更友好的配置界面"就能做到的。因为配置界面只能组合平台已经开放给你的动作，而"解析文档 → 推断字段 → 建表 → 发布 → 升版"这条链路，横跨了平台里几个不同的执行环境和权限层，中间还夹着若干只有实际跑过才知道的行为约束。

真正的转折点，是把平台自身的运行规则当成"可编程的素材"来用。低代码平台并不是只有"配置界面"这一层：界面上每一个配置动作，底层都对应明确的执行环境与权限分层——谁能建表、在哪一层发布、元数据存在哪里、脚本在哪个沙箱里跑。这些规则，文档通常只描述能力，不描述它们怎么组合。

这就是本次需求的核心难点，也是 AI 真正的增量所在

难点不在任何单个功能，而在一次"平台底层逻辑的再加工"：把原本只有开发人员能做的动作，重新编排成业务人员点几下就能完成的事。

大模型在这里的价值，不是"代码写得快"，而是它能读透一个陌生平台的分层规则，并把它重新编排成另一种使用方式：

① 先弄清权限分层——用户端能做什么、设计端才能做什么，由此撞上"用户端不能建表"这条硬边界；

② 再把边界两侧的动作串成一条链：前端点一下 → 请求进入有权限的那一层 → 建表 → 发布 → 回到前端提示完成；

③ 最后把这套逻辑固化成元数据驱动的机制：表单长什么样不写在代码里，而是存在一张注册表里——于是"新增一张表单"不再是一次开发，而是新增一条记录。

也正因为这条链路每一环都踩在平台的分层边界上，它成了整个项目里返工最集中的地方：第 2 章步骤 4 的两次返工都发生在这里，第 5 章的四个案例里也有两个（案例 1、案例 2）直接出自这条链路。

1.5 本次交付什么，以及明确不做什么

范围收敛后是三块能力，每块都有可验收的终点：

能力	使用者	验收终点
业务人员自助建表	客户方业务人员	上传一份原始文件 → 核对字段 → 点一下，系统里出现可用的数据表和交互界面，全程只在织信使用界面操作
多级审批流转	填报人 + 各级审批人	按 3–4 节点单流程流转，每节点可同意/驳回，全程留痕
台账版式还原打印	业务人员	勾选 N 条记录 → 得到一个 Word 文件，打印效果与上传的源文件一致

同时有四项是明确不做的，都是问答里一句句划掉的，省下了大量无效设计：

• 不做产品表：每个表单单独一套数据链，不与表单之外的东西关联，表单之间也不共用数据表。
• 不做电子签名：不碰签批这一层。
• 不做补录：不考虑历史纸质的回溯录入。
• 不做复杂流程：只考虑 3–4 节点的单流程审批，没有分支、没有会签、没有并行。

"不做什么"这一节，是这次协作里性价比最高的部分

这四条基本都是我在方案里列成问题问出来的，对方一句话就答了。如果没有这次问答，我很可能会去做产品表关联、去做电子签名占位、去做多分支流程——每一样都要花时间，而且做完还得删。砍范围的成本几乎为零，判断错了的成本却很高。

第 2 章 推进时间轴：七步走完全程

这一章把整个过程按实际发生的顺序拆成七步。每一步都写清楚：为什么做这一步、具体做了什么、产出什么、卡在哪里。读者可以把它当成一张"路线图"——照着走，能避开我们踩过的坑。

七步推进轨迹：颜色代表该步的"健康度"——蓝=顺利，橙=有返工，绿=打通，红=反复失败

逐步详解

方案设计：先把"纸"翻译成"数据模型" — 起点 · 86 分钟

为什么先做这一步：表格结构没定就动接口，等于边盖楼边改图纸。

• 做了：把真实 Word 表单逐张拆解，列出每张表的字段、分组、必填规则；同时设计"工厂侧"的元数据表——系统要能管理自己的表单版本、流程版本、发布队列、变更日志。
• 产出：一份方案文档（期间迭代了三版才定稿）：数据模型图 + 流程梳理 + 平台能力对照。
• 关键：方案里必须显式回答"平台能否做到、怎么做"，不能只讲业务构想。这一条后来被证明是省返工的关键。

搭应用骨架：分组、元数据表、导航 — 地基 · 5 分钟

为什么单独做这一步：低代码平台里，结构不对会导致后面每一步都在迁就它。

• 做了：建三个功能分组（表单台账 / 表单审批 / 表单工厂），建 7 张元数据表：表单注册表、版本快照、流程版本、导入任务、发布队列、变更日志、收藏。
• 产出：一个能跑起来的空应用，导航结构清晰，元数据表之间已建立关联。
• 卡点：写操作必须串行执行——并行建表会互相覆盖，导致表没挂进应用树。这条约束后来写进了操作规范。

建第一张业务表 + 审批流：验证"一条路能不能走通" — 主链路验证 · 12 分钟

为什么选一张真实表而不是造个 demo：真实数据能暴露所有结构问题。

• 做了：拿真实的《偏差申报表》建表：32 个字段、7 个分组，挂到"质量"分组下；配 4 节点线性审批（部门负责人 → 现场 QA → 偏差管理 QA → QA 负责人），每节点含同意与驳回。
• 产出：一个能录入、能提交、能审批、能归档的完整单据流程。
• 卡点：字段默认值在服务端流程里不生效。原本想靠字段默认值自动生成版本号和状态，实测发现建单时不写就是空——只能改成"由创建入口显式写入"。

做自助建表：让业务人员自己上传 Word 生成系统 — 两次返工 · 67 分钟

这是整个项目最有野心的部分：把"开发能力"交到不懂技术的人手上。

• 设想：业务人员上传一份 Word → 系统解析出字段 → 弹出清单让人核对 → 点确认 → 自动建表、自动发布。改版时再上传新文件，系统自动识别变更并升版。
• 现实：返工一：最初设想业务人员端就能直接建表，做完才发现用户端脚本没有建表权限——整个链路的前提错了。改成"脚本发起请求 → 设计端执行建表 → 自动发布"这条绕道路径。
  • 返工二：上线后点【启动创建】，弹出的字段清单一条都没有。原因是解析器在真实文件上崩了（正则吞掉整段文档结构），而界面上看不出"解析失败"和"确实没字段"的区别。
• 产出：两条自动化链路（新建 + 改版升版），加一个能人工核对字段的动态表格确认弹窗。
• 教训：这一步的两次返工，一次源于没先确认"这个动作该在哪个执行环境里做"，一次源于解析逻辑只在构造样本上验证过。凡是"跨端协作"的链路，必须先把权限边界问清楚（详见第 5 章案例 1、案例 2）。

版式还原打印：把系统再变回纸 — 技术难点 · 48 分钟

因为业务部门只认原版式，这一环不做，整个系统就没有闭环。

• 思路：不重新"画"一份报表，而是把原 Word 文件改造成模板：找到固定填位（下划线、空格），替换成数据标签；把表格的循环行标记出来；保留所有样式不动。
• 做了：① 抽取"版式锚点"：识别表头行、循环行、列数、每页行数、空行数、列与字段的映射、文档级字段（如页眉里的车间、版本号）。
  • ② 生成模板：解包文档 → 在循环行打标签 → 表头设为跨页重复 → 删除多余空行 → 段落打标签 → 重新打包。
  • ③ 渲染：取版本 → 取锚点 → 按每页行数切块 → 填数据（不足补空行）→ 合并成单个多页文件。转 PDF 的能力平台是有的、也单独验证通过，但本次没有接到按钮上。
• 产出：真实源文件 35.5 KB → 模板 31 KB → 渲染 9 条记录得 2 页文件 33.4 KB，样式 100% 保留（字体、列宽、边框、合并单元格、页眉页脚）。
• 卡点：解析时把表头一个单元格里的多段文字拆成了两个字段（"滤器类型"变成"滤器"+"类型"），导致打印这一格是空的。修复要同时改版本快照、版式锚点、模板三处——因为字段是它们的共同依赖。
  • 另外页眉的两个字段渲染成空：原因是把"纯空格"的排版片段误判成了填充位，标签错位。

最后一公里：让文件真的落到用户手上 — 改了四版 · 29 分钟

这是被严重低估的一步。文件生成成功 ≠ 用户拿到文件。

• 现象：点【打印选中】后，界面提示"开始下载"，但浏览器下载目录里什么都没有。文件在服务端确实生成了。
• 四版：V1：下载步骤用"原始内容"模式，但只给了文件路径 → 提示成功、无文件。
  • V2：换"共享存储"模式 + 固定路径 → 报"文件不存在"，且路径里带着多余引号。
  • V3：签发临时直链、前端开新窗口去取 → 完全没反应（新窗口被浏览器拦截）。
  • V4：脚本读成 Base64、前端按内容生成文件 → 得到一个名为 undefined 的空文件。
• 破局：停止继续改代码，改用外部工具独立验证：用命令行直接请求脚本签发的直链，一次拿到"200 / 33,375 字节 / 首字节 PK / 可解包 25 个部件"。这证明"文件 + 链接"这条链路本身成立，问题只在前端怎么用。
• 教训：四个变量同时在改（模式、路径来源、触发方式、参数格式），所以每次都归因错。详见第 5 章案例 3。

收尾：清理临时物、沉淀规则 — 交付 · 穿插进行

不清理的代价是后来的人分不清哪个是正式功能。

• 做了：把所有踩过的坑整理成"现象 → 根因 → 正确做法"的规则清单；把能力矩阵（平台能做什么、参数怎么传）写进项目记忆，让下一次会话不用重新试一遍。
• 产出：一份可交接的规则清单，让下一个接手的 AI 会话不必重新踩一遍。
• 没做完：留下的一个调试脚本和一张自测表没清掉——平台没有对应的删除接口，只能人工去删。选择调试方式时就要考虑"怎么撤"，否则调试产物会永久留在应用里。

七步的投入分布（实测，不是估算）

下表的时间不是我事后估的，而是从会话记录里逐条工具调用的时间戳反推出来的。口径：取该步第一个实际操作到最后一条产出的墙钟时间，含期间的人工核对；不含步骤之间的等待。

步骤	时间窗	实测耗时	占比	返工 / 主要消耗
1 方案设计	10-19 17:05–17:28 10-20 09:05–10:07	86 分钟	34%	3 版。把业务语言翻成数据模型，以及等对方回答 8 个待确认问题
2 搭骨架	10-20 10:53–10:58	5 分钟	2%	0。3 个分组 + 7 张元数据表一次建成
3 首张业务表	10-20 10:59–11:11	12 分钟	5%	0。32 个字段 + 7 个分组 + 4 节点审批流 + 发布
4 自助建表	10-20 13:46–14:53	67 分钟	27%	2 次。一次权限边界推倒重来，一次解析器在真实文件上崩
5 版式还原	10-20 15:42–16:30	48 分钟	19%	3 次。模板打标、页眉字段错位、表头被拆成两列
6 最后一公里	10-20 16:31–17:00	29 分钟	12%	4 版。下载链路的四层假设连环踩空
7 收尾	穿插在各步末尾	约 3 分钟	1%	0。没有独立时段，规则随踩随记
合计	10-19 17:05 → 10-20 17:00	250 分钟 ≈ 4 小时 10 分	100%	11 次返工 / 迭代

项目跨度是 近 24 小时，但真正在推进的只有这 250 分钟。剩下的时间里：隔夜约 15.6 小时、午休约 2.6 小时，另有约 1.5 小时是对方在看效果、报问题。

实测数据推翻了一个直觉

平台原生的配置动作几乎不花时间。搭骨架 5 分钟、首张业务表 12 分钟——3 个分组、7 张元数据表、32 个字段、4 个审批节点，加起来只占 17 分钟（7%）。如果只看这部分，会以为"低代码 + AI 真快"。

但真正的时间花在另外两处：想清楚（方案设计 86 分钟，34%）和踩坑后重建（自助建表 67 分钟，27%）。最后一公里只用了 29 分钟，却改了 4 版，单位时间的产出最低。

所以这份手册把重心放在"怎么少踩坑、怎么快速确认能不能跑"，而不是放在功能设计上——因为 AI 已经把"做"的成本压到很低了，剩下的成本全在"想"和"验"上。

第 3 章 七阶段实操手册

第 2 章讲"按时间顺序发生了什么"，这一章讲"每个阶段该用什么方法"。每个阶段统一四栏：目标 / 你要做什么 / AI 该做什么 / 验收标准，末尾附"常见塌方点"。

四栏的分工是刻意的：人负责判断和拍板，AI 负责探测和执行。凡是"拍板"的部分交给 AI，都会出问题；凡是"执行"的部分人自己上手，都会变慢。

1. 素材准备　—　让 AI 有确定的东西参考

你要做什么

• 提供原始文件，不是描述
• 说明业务场景与使用人
• 指定一个具体样本作为验收基准

AI 该做什么

• 解包/读取真实文件，不假设结构
• 把样本的数据特征写出来给人确认
• 建立"一个应用一个素材子目录"的约定

验收：AI 能复述出样本文件的关键结构（有几列、哪些位置要填数据、哪些是固定文字），且与你认知一致。

塌方点：用形容词代替文件

"做一个差不多的台账表" —— AI 只能自己编结构，编出来的东西你一定不满意，然后开始无限返工。一个真实文件胜过十句描述。

2. 方案与数据模型定稿　—　先定框架，再谈逻辑

你要做什么

• 确认字段的业务含义与必填规则
• 确认分组与菜单归属
• 对"看起来像两个字段"的地方做裁决
• 拍板业务规则（每页固定几行、不足怎么补、版本怎么升）

AI 该做什么

• 产出表清单 + 字段清单（名称/类型/分组）供审阅
• 标注每个字段的数据来源（手填/计算/带入）
• 写操作串行执行，避免配置互相覆盖
• 方案里显式写明"哪个动作在哪个执行环境落地"

验收：字段能建出来、能保存、能在列表看到；字段清单与业务认知一致。

经验：字段是后面所有环节的地基

打印阶段发现"某列被拆成了两个字段"，修复它要同时改版本快照、版式锚点、模板三处——因为字段是它们的共同依赖。地基上的偏差，会在每一层放大。

3. 主链路打通　—　最短路径先跑通

你要做什么

• 指定一条最短路径（例：一个文件 → 一张表）
• 明确这条路径的终点现象
• 暂时接受"其他情况不支持"

AI 该做什么

• 只在主链路上做完整实现，分支先留桩
• 每个环节都留可观察痕迹
• 跑通后再回来补分支与异常

验收：用真实素材端到端跑一遍，产出物能打开、内容正确。

塌方点：一开始就追求"全面"

同时支持台账与申请单两类表单、同时支持 Word 与 PDF 两种输出 —— 结果每一路都是半成品，谁也用不了。先让一条路能走通全程，再让它变宽。

4. 交互装配　—　把能力接到用户手边

你要做什么

• 说清触发方式（列表勾选 / 详情页按钮 / 定时）
• 说清期望的交互反馈（弹窗/下载/提示）
• 确认权限范围（谁能看到这个按钮）

AI 该做什么

• 选择正确的步骤类型（服务端逻辑 vs 客户端交互）
• 把变量绑定关系写清楚，参数做规整化处理
• 注意执行环境差异：客户端才能弹窗，服务端不能

验收：在真实界面点一次，得到预期反馈。这一步必须由人点，无法服务端模拟。

塌方点：混淆服务端与客户端执行环境

定时任务、事件监听、流程回调都是服务端执行，不能有弹窗/下载类步骤。把"下载文件"放进服务端执行的自动化里，注定无声失败。

5. 端到端自测　—　交付前必须由 AI 自己跑一遍

你要做什么

• 把这条要求明确写进需求："改完先自测，跑通再给我"
• 只做验收，不做第一轮测试

AI 该做什么

• 用真实数据 + 极端参数跑（空值、超长、跨页、带引号）
• 下载产出物回来解包校验，不只看"返回成功"
• 把发现的问题全部修完再交付，附实测数据

验收：交付说明里能列出"我测了什么、结果如何、还剩什么已知限制"。

这是本项目最有价值的一条协作规则

用户的原话是：「你能否修改发布完成后，先自行模拟测试一遍，并且解决过程中遇到的所有问题，确保跑的通再交给我。」

这一条把"用户当测试员"变成"AI 当测试员"，直接把协作效率提了一个台阶。建议每个项目开工第一句就把这条立起来。

6. 发布与验收　—　不可逆动作用确认制

你要做什么

• 对发布类动作明确说"发"或"不发"
• 验收时按验收基准样本逐项对照
• 把不满意的点具体化（"第 3 列没值"而非"不太对"）

AI 该做什么

• 不自行发布：影响线上环境的动作必须显式征询
• 发布后立即复测，而不是默认"发布=生效"
• 交付时给可操作的验证路径（点哪里、看什么）

验收：用户在真实界面完成一次完整操作，结果符合基准样本。

塌方点：把"发布"当成技术细节

发布是应用级、影响所有用户的动作，且重复发布有风险。这类动作必须有明确的人工确认环节，不能由 AI 自行决定。

7. 迭代修复　—　先用痕迹定位，再动手改

你要做什么

• 报现象要精确：点了什么、看到什么、期望什么
• 报错贴原文，不要转述
• 如果连续两轮没修好，要求换思路而不是继续试

AI 该做什么

• 先查中间痕迹判断卡在第几步，不猜
• 明确说出"我怀疑是 X，因为 Y 证据"
• 修复要能解释"为什么之前不行、现在为什么行"

验收：修复说明里同时给出了根因、证据、和验证方式。

故障定位四步法

① 看痕迹判断断点在哪一步 → ② 缩小到单个变量 → ③ 用最小实验证伪/证实 → ④ 改一处、再验一次。

详见第 5 章案例，尤其是案例 3 —— 那一轮我们违反了这套方法，代价是四版。

第 4 章 开发问题—发现到解决

这一章是全篇最有教学价值的部分。四个案例都来自真实项目，包含判断错的地方。每个案例用统一结构：现象 → 排查路径 → 根因 → 修法 → 可复用教训。

案例 1 · 字段清单为空：建表第一步就卡死

• 现象：上传 Word 后点【启动创建】，弹出的"核对字段清单"里一条字段都没有，无法确认，流程走不下去。
• 排查：把解析出的中间结果打印出来看——发现解析器只从表头里识别到 1 个字段，其余全部丢失。而"丢失"这件事在界面上看不出来，界面只是安静地显示了一个空列表。
• 根因：提取文档文本的匹配规则写成了"标签名后面必须跟属性"这种形式。它假设目标标签总带属性；一旦遇到不带属性的裸标签，匹配会越过自己的闭合位置，把后面一大段内容吞掉。整段文档结构被破坏，后续字段自然提不出来。
  • 这是一个典型的"在正常样本上刚好能用、在真实样本上崩掉"的错误。
• 修法：把标签匹配改成"属性部分可有可无"的形式，并对自闭合标签单独分支处理。改完用真实样本回放，字段数从 1 恢复到 12。
• 教训：① 解析类逻辑必须用真实文件回放验证，不能用构造的简化样本。
  • ② 界面无数据时，要区分"确实没有"和"解析失败"——本例中两者在 UI 上长得一模一样，这是设计缺陷，后来改成"解析失败要弹出诊断信息"。

案例 2 · "第一行必填数据格式错误"：键名对不上

• 现象：字段清单能看到了，点提交却报"第一行必填数据格式错误"。字段名、值都肉眼可见是对的。
• 排查：把即将提交的数据结构完整打印出来，与平台要求的格式逐键对比。发现取值的键名和快照里实际的键名不一致 —— 读出来全是 undefined，于是"必填为空"。
• 根因：平台不同来源的数据结构命名不一致：接口文档里叫 A，实际快照里叫 B。按文档写代码，就拿到一堆 undefined，而且不报错——undefined 是合法值。
• 修法：加一层归一化：取值时做 f.id || f.fieldId 兼容，并把数据结构打印进诊断日志。
• 教训：① 跨模块传数据前，先 dump 一次真实结构，不要相信文档里的字段名。
  • ② undefined 是最危险的错误，因为它静默。取值处应主动判断并抛错，而不是让它流到下游。

案例 3 · 重点 · "提示开始下载，但实际没有文件"——改了四版才找到根因

这是本项目最贵的一课，也是唯一一个改了四版的功能。完整记录如下，包括我们做错的地方。

先说结论：四版都没能让用户真正拿到文件，最后收口的是"文件生成完全正确 + 链路成立 + 根因逐层定位"，而不是一个可用的下载按钮。手册保留这个不圆满的结尾，因为它比一个漂亮结论更有教学价值——看起来每一步都在推进，实际上一直在换方向重试，这是最典型的失败模式。

现象

点【打印选中】按钮后，界面提示"开始下载"，但浏览器下载列表里什么都没有。文件确实生成了（服务端有产出），只是交不到用户手上。

四版收敛过程

版本	做法	结果	当时的判断
V1	下载步骤用"原始内容"模式，但只给了文件路径（指向脚本临时目录）	提示成功，无文件	以为"给了路径就能下载"
V2	换成"共享存储"模式 + 固定存储路径	报"文件不存在"，路径里带着引号	以为是模式问题，其实是参数被污染
V3	脚本签发临时访问链接，前端打开新窗口去取	完全没反应	没意识到新窗口被浏览器拦了
V4	脚本把文件读成 Base64 字符串，前端按内容生成文件	得到一个名为 undefined 的空文件	变量绑定/大字符串传递不可靠

四版都失败，问题出在方法而不是技术

我们把"下载模式、路径来源、触发方式、参数格式"这些变量同时在改。每次失败都换一个方向，却从没真正验证过任何一条链路在外部看来是否成立。这就是违反"一次只改一个变量"的代价。

真正解决问题的那一步

转折点不是又改了一版代码，而是换了一种验证方式：把"文件能不能被匿名访问"这件事从平台里剥离出来，用外部工具直接验证。

# 让脚本签发一个带时效的临时直链，然后用完全独立的方式去请求它
curl -s -D headers.txt -o out.bin "https://<host>/<token-path>"

# 看三件事：状态码、字节数、首字节是不是文件魔数
# HTTP/1.1 200           ← 能访问
# content-length: 33375  ← 完整文件
# 首字节 PK             ← 合法的 zip/docx
# content-disposition: attachment; filename="..."  ← 会触发下载

结果一次就拿到了：200、33,375 字节、首字节 PK、内容可解包出 25 个部件。这说明"文件 + 链接"这条链路是完全成立的——问题只在于前端怎么用它。

逐层剥开的四个真实原因

层	原因	为什么难发现
数据层	"原始内容"模式读的是内容变量，根本不看路径变量	参数名相似，且填了不报错
路径层	脚本临时目录是沙盒路径，脚本结束即失效，浏览器无法访问	服务端能读到，看起来"文件存在"
浏览器层	新窗口打开会被弹窗拦截——多步异步调用后已失去"用户手势"上下文	拦截是静默的，不报错不提示
传递层	把 4 万多字符的 Base64 塞进流程变量，绑定链路不可靠	表现为 undefined，像是代码 bug，其实是数据传递问题

可复用教训（这一段建议直接抄进你的规范）

四条硬规则

① 先证明"东西是对的"，再证明"能交到手上"。这两件事分开验证，不要混在一次改动里。

② 给浏览器文件，优先用"临时带签名的直链"，不要依赖前端自己去解析存储路径。直链可以用任何工具独立验证，这是它最大的价值。

③ 不要在多步异步之后开新窗口。浏览器只认"紧贴用户点击"的窗口调用；要下载就用平台提供的下载步骤，不要自己开窗。

④ 不要用流程变量传大块二进制内容。传"引用"（路径/令牌），不传"本体"。

还有一个保底设计

正确的下一步不是再改第五版，而是把生成的打印件同时存到"打印留痕"记录的附件字段里——这样即使下载链路不通，用户也能从记录列表里直接拿到文件。这件事本次没来得及做，是复盘后认为最该先做的一件。

凡是"最后一公里"不确定的功能，都应该先准备一条平台原生的保底通道。

案例 4 · 路径里带着引号：错误信息里的字面量

• 现象：报错原文：打印件不存在(请先生成): print/'QA-10002'/download.'docx'
• 排查：报错信息本身就是最好的线索——路径里出现了不该出现的单引号。用带引号和不带引号两种参数各调一次，立刻复现：带引号时取不到任何东西，不带引号时正常。
• 根因：配置自动化步骤时，参数写成 'QA-10002'，以为会按代码里的字符串字面量解析。但平台的表达式引擎对不带变量标记的值按原样字符串处理——连引号一起传进去了。
• 修法：两件事同时做：① 把所有入口函数的参数做统一规整（剥掉成对的外层引号，数字串转数字）；② 参数尽量不带引号书写。

  // 入口参数清洗：让函数对"带引号"和"不带引号"都免疫
  function rawArg(v) {
    var s = String(v == null ? '' : v).trim();
    if (s.length > 1) {
      var f = s.charAt(0), l = s.charAt(s.length - 1);
      if (f === l && (f === "'" || f === '"' || f === '`')) s = s.slice(1, -1).trim();
    }
    return s;
  }

• 教训：① 凡是会被自动化/按钮调用的函数，入口必须做参数清洗。不要假设平台会帮你解字符串字面量。
  • ② 报错信息里要带出实际值，而不是只说"失败"。本例中正是因为错误信息里打印了拼接后的路径，才能一眼看到引号。这是"留可观察痕迹"的又一次收益。
  • ③ 修完后要按出错的调用方式复测（故意全用带引号参数），而不是用"干净"的参数测。

四个案例的共同结构

共同点	含义
都是静默失败	不报错、或报了模糊的错，看起来是"没反应"
根因都不在业务逻辑，在边界交接处	数据结构交接、路径交接、浏览器与服务器交接、配置与代码交接
靠打印中间值破局	四个案例全是"把中间数据打出来看"之后才定位的
修复都要回放到出错场景	用正常参数测通不算通，要用出错时的参数测通

第 5 章 提问模板库：如何有效提需求

同一个需求，问法不同，产出质量差别巨大。这一章是从本项目真实对话里提炼的十组对照，可直接套用。

	说法	说明
❌ 差	"帮我做个表单管理系统"	AI 只能自己编范围，编错了就全返工。
✅ 好	"客户是一家生物研发公司，有 1000 多个表单，每个表单在不同研发阶段还会改版。使用者是不懂 IT 的业务人员，希望自己在织信使用界面导入 Word 就能生成表单和交互界面，不走后台开发。先帮我出一套方案，先不要开发。"	给了场景、规模、使用人、交付形态，还明确"先方案、后开发"——第一版方案就是照这个问法出的。

	说法	说明
❌ 差	"这块不行，你看看"	没有现象，AI 只能从十个方向里猜。
✅ 好	"测试了一下，提示开始下载，但是实际上未下载。"	一句话，却直接分开了"文件没生成"和"文件生成了但交不到手上"两种可能——砍掉一半排查方向，剩下的只是定位交不出去的原因。

	说法	说明
❌ 差	"报错了，你修一下"	转述会丢掉关键细节，尤其是路径、ID、引号这类字符。
✅ 好	"提示自动化步骤执行失败：Error: 打印件不存在(请先生成): print/'QA-10002'/download.'docx'"	原文里那个引号直接指向了根因，一转述就没了。

	说法	说明
❌ 差	"打印出来的效果不太对"	"不太对"是无法执行的信息。
✅ 好	"生成的是一个undefinded的文件 不是word文件"	指名了文件名和文件类型——和"打不开""没反应"相比，这一句直接指向"内容没传到前端"，也就是变量绑定问题。

	说法	说明
❌ 差	"版本这块你看着办，能改就行"	"能改"是最低要求，AI 会给一个最简单的实现——而版本恰恰是最需要精确定义的地方。
✅ 好	"业务人员不仅需要可以创建表单，还需要可以修改表单，每次修改，表单的版本都会加 1，但是不影响历史版本，历史数据会记录当时自己的表单版本，后续可追溯。"	一条规则里同时给出了"谁能改、怎么计数、历史怎么办"——版本这块的设计就是照这句话定的。

	说法	说明
❌ 差	逐条讨论："第一点可以，第二点我再想想，第三点……"	多轮来回，且容易遗漏。
✅ 好	"待确认问题答复 1、修改这个动作是由用户主动点击…2、用户提交，具体操作流程参考答复1…（共 8 条）"	八个开放问题，一次编号答完，没有一轮追问。方案定稿靠的就是这一次回复。

	说法	说明
❌ 差	"能不能再快一点"	催促不产生信息，只会让 AI 跳过验证。
✅ 好	"改完发布后，先自行模拟测试一遍，把过程中遇到的问题都解决，确保跑通再交给我。"	把压力加在"验证"环节而不是"速度"环节——质量反而更高。

	说法	说明
❌ 差	"要支持所有类型的表单"	范围无边界，等于没有需求。
✅ 好	"1、先做台账类型 2、留空 3、固定行数"	一个编号答复同时砍掉另一类表单和另一种排版策略，让第一条链路能真正跑通。

	说法	说明
❌ 差	"想做个打印功能，你看着设计"	没有基准样本，AI 只能自己定义"打印成什么样"，定义完你还得推翻。
✅ 好	"以「XX 过滤器使用_台账」这份文件为例，如果我勾选部分记录打印，最终效果也要和这份源文件一致，帮我出个方案。"	给了基准样本 + 明确的验收口径（"和源文件一致"）。

	说法	说明
❌ 差	"你看什么时候方便就弄吧"	模糊授权，AI 只能自己决定方案、平台、范围、命名——每一项都可能选错。
✅ 好	"先按这个方案，开始用织信平台，新建一个应用开发，应用就叫表单管理系统"	一句话给全了四件事：按哪个方案、用什么平台、做什么动作、叫什么名字。没有任何需要回头追问的地方。

三个高效习惯（比模板更重要）

习惯	为什么有效	本项目实例
编号回答决策点	多决策一次拍完，不产生来回	"1、先做台账类型 2、留空 3、固定行数"
报错贴原文	保留字符级线索，往往是根因所在	路径里的引号直接暴露了参数污染
给成品当标准	验收标准客观化，不靠感觉	"最终效果也是生成我上传的这份源文件"

还有一个反直觉的经验

提需求时"少说要什么功能，多说不要什么"。这次真正省时间的几句都是排除句："不需要考虑产品表"、"不需要电子签名"、"不需要补录"、"不影响历史版本"——每一句都直接砍掉一整块设计。排除项比需求项更能锁定实现路径，也更容易验收。

第 6 章 检查清单：Skill能力补充

可以参考，把觉得有价值的，加入你的skill！

开工前六项：把地基打对

1. 有没有讲清楚现状与痛点（不做会怎样）？
2. 有没有提供真实素材（文件/截图/系统导出），而不是描述？
3. 有没有指定一个验收基准样本？
4. 数据模型（表 + 字段 + 分组）是否已定稿并确认？
5. 范围是否已主动砍到最小可跑通路径？
6. 是否已立下"AI 自测跑通再交付"的规矩？

每次改动后五项：AI 的自检

1. 这次改动只动了一处吗？
2. 用真实数据跑过端到端吗？
3. 用出错时的参数形式复测过吗？
4. 产出物有没有取回来真的打开看？
5. 有没有新的坑需要写进规则？

上线前九项：交付门槛

1. 字段清单与业务认知完全一致（含命名、必填、类型）？
2. 空值、超长、特殊字符都不会导致崩溃？
3. 跨页、多记录、单记录三种场景都验证过？
4. 权限范围正确（谁能看、谁能操作）？
5. 失败时有可读的错误提示，不是静默失败？
6. 有保底通道（主要路径失败时还有办法拿到结果）？
7. 关键操作有留痕（谁、何时、做了什么）？
8. 临时产物（测试表、调试脚本）已清理？
9. 已告知用户已知限制，不含隐藏问题？

出故障时五问：定位框架

1. 这个功能有没有留中间痕迹？痕迹显示走到第几步？
2. 现象能不能用一句话精确描述（不含"不对""有问题"）？
3. 最近一次改动动了什么？能不能先回退验证？
4. 这个不确定性能不能拆成一个最小实验单独验证？
5. 我是不是在同时改多个变量？