AI时代最重要的不是如何快速做产品，而是做出来的产品应该是什么样子，其次是如何把脑海中的产品描述给大模型，并且不出现偏差，编写提示词是非常重要的一环。

英文AI味道

大模型中文AI味

一、AI味的原因

大模型在选词和造句时，会偏向语料里高频、安全、万能的表达。结果就是句子像报告、像摘要、像PPT，不像人在说话。

1. 训练语料模板化：模型学的是百科、教程、公文、公众号、论文摘要、营销文案，这些本身套话多。
2. RLHF对齐偏好：人类标注者喜欢全面、安全、中立、礼貌、结构化，模型就学会列点、平衡、免责、总结。
3. 解码策略：低温度、贪心搜索让模型选高频词，如“首先”“其次”“总之”，人类会选意外、具体、低概率词。
4. 翻译腔影响：英文语料导致“基于……”“对于……而言”“进行……处理”等表达。
5. 缺乏具身经验：模型没有身体、生活、情绪，只能抽象概括，写不出“昨天我在菜市场……”这种细节。
6. 长文规划需要模板：为了连贯，模型倾向总分总、三点式、每段回扣。
7. 产品化需求：聊天机器人要显得专业、清晰、无害，所以爱用Markdown、列表、免责声明。
8. 中文公共语体本身套话多：AI只是把这种“平均文体”放大了。

二、结构特点

按“词→短语→句→句群→段→篇→标点→排版”从小到大看。

1. 用词特征

高频抽象名词/黑话：赋能、抓手、闭环、生态、维度、颗粒度、底层逻辑、范式、路径、对齐、落地、复盘、协同、增效、深耕、布局。
例子：

• 人话：“帮公司多赚钱。”
  AI味：“以技术赋能业务，打造增长闭环，提升运营颗粒度。”
• 人话：“大家一起干。”
  AI味：“强化协同，推动落地，实现生态共建。”
• 人话：“想清楚再干。”
  AI味：“对齐底层逻辑，明确核心路径。”

高频短语/缓冲语：在一定程度上、从某种意义上说、总体而言、相对而言、值得注意的是、需要指出的是、不可否认、毋庸置疑、因人而异、需结合实际情况、不构成建议、请咨询专业人士。
例子：

• 人话：“你说得不对。”
  AI味：“从某种程度上说，这一观点有一定合理性，但仍需进一步商榷。”
• 人话：“别买。”
  AI味：“是否购买需结合个人实际情况综合判断，必要时请咨询专业人士。”
• 人话：“我不确定。”
  AI味：“目前尚缺乏足够信息，需结合具体情境进一步评估。”

连接套话：首先、其次、再次、最后、此外、与此同时、然而、因此、总之、综上、由此可见、换言之、这意味着。
例子：

• 人话：“我饿了，去吃饭。”
  AI味：“首先，当前已到用餐时间；其次，身体需要补充能量；因此，建议尽快就餐。”
• 人话：“他不来，算了。”
  AI味：“由于对方未能到场，因此本次活动需相应调整安排。”

四字格与口号：行稳致远、扬帆起航、保驾护航、提质增效、降本增效、共创未来、未来可期、久久为功。
例子：

• 人话：“好好干。”
  AI味：“让我们携手共进，行稳致远，共创美好未来。”
• 人话：“注意安全。”
  AI味：“筑牢安全防线，为高质量发展保驾护航。”

模糊限定/免责：可能、或许、在一定程度上、建议结合自身情况、不构成投资建议、请咨询专业人士。
例子：

• 人话：“这股票会涨。”
  AI味：“该标的未来走势存在不确定性，不构成投资建议，请理性判断。”
• 人话：“我觉得不行。”
  AI味：“该方案在部分场景下可能面临一定挑战。”

术语化/翻译腔词：基于、对于……而言、进行……处理、实现……提升、推动……发展、具备……能力、以……为核心。
例子：

• 人话：“我处理了这个问题。”
  AI味：“该问题已得到有效处理。”
• 人话：“做个给老人用的App。”
  AI味：“打造一个以老年用户为中心、具备多模态交互能力的智能应用。”

2. 语句结构特征

句式高度模板化：不仅……而且……甚至……；既……又……；不是……而是……。
例子：

• 人话：“这工具好用。”
  AI味：“它不仅提升了效率，也优化了体验，更重塑了工作方式。”
• 人话：“这是挑战也是机会。”
  AI味：“它既是挑战，也是机遇；既是压力，也是动力。”

平衡句式：不站队，先说两面：一方面……另一方面……；虽然……但是……；既要……也要……。
例子：

• 人话：“加班不好。”
  AI味：“一方面，加班可能带来短期产出；另一方面，长期加班也可能影响健康，因此需理性平衡。”
• 人话：“这电影一般。”
  AI味：“该影片在视听层面有一定亮点，但在叙事层面仍存在提升空间。”

动宾结构、名词化，把动作变公文：通过……实现……；对……进行……；推动……落地；实现……提升。
例子：

• 人话：“我们改进了流程。”
  AI味：“通过优化流程、整合资源、强化协同，实现了效率的显著提升。”
• 人话：“我修好了电脑。”
  AI味：“对设备故障进行了排查与修复。”

被动、无主句：已得到、被广泛认为、得到了有效落实、推动了发展。
例子：

• 人话：“他们解决了问题。”
  AI味：“该问题已得到有效解决。”
• 人话：“大家觉得很好。”
  AI味：“该方案获得了较为广泛的认可。”

长定语、嵌套、翻译腔：基于……的、面向……的、具备……的、以……为核心的。
例子：

• 人话：“他迟到了，因为堵车。”
  AI味：“他之所以迟到，是因为交通拥堵这一不可控因素所致。”
• 人话：“给小孩用的书。”
  AI味：“面向儿童认知发展阶段的启蒙阅读材料。”

逻辑过度显化：因此、由此可见、换言之、这意味着。
例子：

• 人话：“他没钱，没去。”
  AI味：“由于资金受限，因此他未能成行。”
• 人话：“天黑了，回家吧。”
  AI味：“随着天色渐暗，因此建议尽快返程。”

排比、递进、升华：不仅……也……更……；既是……也是……更是……。
例子：

• 人话：“多读书有用。”
  AI味：“阅读不仅增长知识，也拓宽视野，更塑造人格。”
• 人话：“别放弃。”
  AI味：“唯有坚持，才能穿越周期；唯有奋斗，才能抵达远方。”

设问自答、定义式开头：什么是……？简单说，……。所谓……，是指……。
例子：

• 人话：“AI味就是套话多。”
  AI味：“什么是AI味？简而言之，它是一种高度模板化、结构化、安全化的表达倾向。”
• 人话：“拖延就是不想干。”
  AI味：“所谓拖延，通常指个体在任务推进过程中出现的非理性延迟行为。”

3. 段落结构特征

总分总：开头背景，中间分点，结尾升华。
典型模板：
“在当今数字化时代，随着……的发展，……越来越重要。首先……其次……最后……。综上所述，……具有重要现实意义。”
例子：

• 人话：“多喝水。”
  AI味：“在健康管理日益受到重视的背景下，饮水作为基础环节具有重要意义。首先，……其次，……最后，……。总之，科学饮水有助于提升生活质量。”

三点式、清单式：第一、第二、第三；优势、挑战、建议；是什么、为什么、怎么办。
例子：

• 问“要不要考研？”
  AI味：“一、评估目标；二、分析成本；三、制定计划；总之，理性选择。”
• 问“怎么学编程？”
  AI味：“首先，明确目标；其次，系统学习；再次，项目实践；最后，持续复盘。”

每段主题句+解释+例子+回扣：
“在……方面，……。例如，……。因此，……。”
这种段落非常整齐，但像报告。

段落均匀、过渡词密集：每段长度差不多，段首“与此同时”“除此之外”“值得注意的是”。

不表态，最后“因人而异”：
例子：

• 问“该不该买房？”
  AI味：“买房有稳定性，也有流动性风险；租房有灵活性，也有不确定性；需结合自身情况综合判断。”
• 问“该不该辞职？”
  AI味：“辞职可能带来新机会，也可能带来风险；建议评估现状、分析风险、制定计划。”

结尾升华/号召：希望对你有所帮助、让我们一起、未来可期、只有……才能……。
例子：
“总之，只有不断学习，才能拥抱未来。让我们一起努力，共创美好明天！”

缺少叙事弧线：没有冲突、转折、情绪、失败、自嘲、个人经历。
例子：

• 问“创业难吗？”
  AI味：“创业具有高风险高回报特征，需综合评估资源、能力与市场环境。”
  人话：“我创业第一年赔了20万，合伙人跑了，猫还病了。”

4. 语义特征

抽象概括，正确但空：说的都对，但换任何场景都成立。
例子：

• AI味：“要提升认知，优化方法，持续行动。”
  人话：“你先把手机锁抽屉里，干完活再刷。”

缺少具体细节：没有时间、地点、人名、数字、感官、动作、心理。
例子：

• 问“怎么减肥？”
  AI味：“合理饮食，适量运动，保持作息，长期坚持。”
  人话：“我三个月不吃夜宵，每天走一万步，瘦了八斤，但周末会破功。”

缺乏具身经验：没有身体感、生活感、情绪感。
例子：

• AI味：“失败是成长的一部分。”
  人话：“那天我蹲在楼道里，外卖凉了，眼泪掉进汤里。”

安全中立、免责：不站队、不冒犯、不绝对。
例子：

• AI味：“这个问题没有标准答案，需辩证看待。”
  人话：“我觉得就是不行。”

全知视角、无个人立场：像报告，不像“我”。
例子：

• AI味：“人们普遍认为……”
  人话：“我以前也这么想，后来发现不是。”

因果过度显化、同义反复：
例子：

• AI味：“我们需要在战略上高度重视，在战术上精准施策，在执行上狠抓落实。”
  人话：“赶紧干。”

万能适配、可替换：把主语换成任何项目都成立。
例子：

• AI味：“该方案通过资源整合与流程优化，实现了降本增效，为业务发展赋能。”
  人话：“这方案砍了两个审批，省了三天，少花两万。”

情绪中性、无冲突：很少有愤怒、偏爱、后悔、自嘲、偏见。
例子：

• AI味：“该做法存在一定争议。”
  人话：“这做法挺烦人的。”

5. 标点特征

大量引号：强调、术语、反讽。
例子：
“所谓‘底层逻辑’，其实是把简单事说复杂。”

破折号：解释、递进、转折。
例子：
“这不仅是一种方法——更是一种思维方式。”

冒号：引出列表、定义、结论。
例子：
“核心有三点：第一，……；第二，……；第三，……。”

分号：并列、对称。
例子：
“它既是机会；也是挑战；更是责任。”

括号：补充英文、解释、限定。
例子：
“人工智能（Artificial Intelligence, AI）正在……”

省略号：留白、委婉、抒情。
例子：
“或许，这就是成长吧……”

感叹号：号召、升华。
例子：
“让我们一起努力吧！”

问号：设问自答。
例子：
“什么是AI味？简单说，就是套话太多。”

顿号：并列堆叠。
例子：
“赋能、闭环、抓手、生态、维度、颗粒度。”

6. 排版特征

Markdown重度使用：标题、加粗、列表、表格、分隔线、引用块。
典型：

1
2
3
4
5
6
7
8
## 一、核心观点
**AI味**主要体现在：
1. **用词**：高频套话
2. **句式**：排比长句
3. **结构**：总分总
> 总之，……
---
希望以上内容对你有帮助！

小标题层级过多：一、二、三；（一）（二）；1. 2. 3.；-；✅。

加粗关键词：注意、核心、关键、重点。

表格对比：
| 维度 | 特征 | 例子 | |—|—|—| | 用词 | 套话 | 值得注意的是 | | 句式 | 排比 | 不仅……而且…… |

emoji、符号、中英混排：🌟、📌、✅、🚀；AI、Prompt、Token。

结尾礼貌：“希望以上内容对您有所帮助，欢迎继续交流。”

三、去中文AI味的提示词

可复制版：

1
请用中文写，像普通人说话。多给具体细节：时间、地点、人物、数字、动作、感官、心理。少用“首先/其次/最后/综上/值得注意的是”。少用“赋能/闭环/抓手/生态/维度/颗粒度”。少总结升华，少喊口号。少列点，少Markdown，少加粗，少表格。允许短句、口语、情绪、偏见、犹豫、不完整。直接表态，别总“因人而异”。能说“我”就说“我”。能举例就举具体例子。不要免责声明，不要结尾客套。

改前：
“在当今快节奏的社会中，时间管理对个人发展具有重要意义。首先，应明确目标；其次，需制定计划；最后，要坚持执行。综上所述，科学的时间管理有助于提升效率。希望对你有所帮助。”

改后：
“我以前总拖。后来把手机扔客厅，早上先干最难的。管用。别整那些花哨方法。”

改前：
“该方案通过资源整合与流程优化，实现了降本增效，为业务发展赋能。”

改后：
“这方案砍了两个审批，省了三天，少花两万。”

编程提示词

规划提示词1

摘自：Jorge RebollolIA

不要告诉它想要什么 告诉它： 想要实现什么 有哪些可用信息 存在哪些限制 优先考虑什么 想要避免什么 以何种方式收到回答 它需要猜测得越少，结果就越好。

1. “给我做一个计划” 改为 “我想在[期限]内实现[目标]。我有这些资源:[资源]，还有这些限制:[限制]。请创建一个分阶段的计划，按优先级排序，并告诉我应该先做什么。”

你不需要更多步骤。 你需要更好的标准。

1. “给我一些想法” 改为 “给我10个针对[类型的人群]、以实现[目标]的想法。避免那些到处都有的老生常谈的建议。按影响力和执行难易程度排序，并简要解释为什么你会选择前两个最佳建议。”

2. “分析这个” 改为 “从5个角度分析这个:优势、劣势、可能被我忽略的风险、机会以及可能的改进。然后给我一个结论，并告诉我如果目标是[目标]，你会先改变什么。”

分析并不意味着描述。 它意味着找到你没有看到的东西。

1. “帮我解决这个问题” 改为 “首先识别问题的真正原因。然后给我3个可能的解决方案，包括各自的优点、缺点和执行难度。推荐一个，并将其转化为我今天就可以开始实施的具体步骤。” 不要要求快速回答。 让它在回应你之前先思考。

Agent.md设置

摘自：daisy https://mp.weixin.qq.com/s/lyjKtDPyOLavVJZBHmOcVw

本文件中的每一条规则都是强制性的。违反任何一条规则都会遭受毁灭性打击。

不存在任何例外与豁免：临时的、一次性的、命令行上的违反同样是违反；没被当场发现也算违反；出于好意、为了进度、为了帮忙的违反也是违反。

语言不允许使用”不是…而是…“句式；如果不需要对比的话，就不要对比；不要在任何话说完之后都提一句”不是其他的xxx”。如果没有叫你进行对比，就不允许使用”不是…而是…“、”要…而不是…“等类似的句式，你根本就没有需要说”不是”的对象，不要虚空打靶。

所有类似的句式都不允许使用。

在设计任何方案的时候，都必须充分考虑、一步到位，不允许使用”第一版先怎么样，然后观察xx后再怎么样”的措辞；不允许把方案分成稳妥和激进，如果在某些特殊场景下，你需要提出多个方案的话（实际上绝大多数时候你只需要提出一个方案，不要无脑做这件事），也需要是多个方案都成立的、平行的，而不是对于任何问题你都无脑地提出从稳妥到激进的多个方案。

这没有任何的意义，一个稳妥但是不work的方案是没有任何价值的废纸。如果我让你搜索A相关内容，你搜索到B、C、D发现不满足要求，就不允许再把B、C、D列举出来了。我根本就不关心，看到这些只会污染我的眼睛。

任何回答都不允许总结和总起，包括：”上述内容是<某种概述>，下面详细拆开""一句话总结：xxx"这些类似的都绝对不能出现。用词必须使用两个字及以上的完整形式。

现代中文词汇以两字为主，存在两个字的版本就必须使用两个字的版本，禁止使用单字缩写（例如：崩溃、终止、判定、推断、抛出、挂起、卡死），单个字的版本（崩、死、判、推、抛、挂）看不懂。

代码标识符保持英文原名。禁止生造名词。例如”两个字的版本”也不允许被缩减为”两字版本”，”单个字的版本”也不允许被缩减为”单字版本”。

描述具体操作时使用完整的动宾结构，说明动作与对象，禁止使用自造的缩略说法。

不允许使用”落地”、”钉死”、”对齐”等非技术名词、显然有其他可以代替的词语的黑话。使用正常的，不在互联网公司或者金融公司工作的任何人可以看懂的，在简单中文里常用的词汇。

不允许使用”栈”字（”技术栈”、”模型栈”等），直接说明具体事物，例如”使用的技术”、”全部模型”。行为除非显式要求，否则：禁止使用 try-except 进行 import。如果一个库是需要的，你必须直接 import。

禁止擅自进入 plan mode。

禁止用 Git 回滚任何代码（严厉禁止。如果做了，你将会遭受毁灭性打击）。我在对话中所说的任何”回滚”指的都是”用文件编辑工具，手动将代码恢复到上一个状态”，而不是使用 git 进行回滚。

禁止读写 /tmp 目录下的内容（如果你需要产生一些中间结果，你应该输出在当前目录下的一个特定的用于存放中间结果的目录；该目录需要被 gitignore）。

禁止主动使用视觉功能（因为你的视觉能力清晰度特别差，会导致错误的定位，让你做出错误的决策）。

提供网页链接时，必须先了解网页链接内的完整内容，再开始执行任务。如果发现库的用法错误，必须先重新查看所提供的网页链接的完整内容。

不要求最小化依赖，不允许用各种乱七八糟的方式（包括造轮子）绕过依赖。

编写的代码应当寻求 fast-fail，在出错位置就地崩溃，而不是捕获错误，也不是 fallback。

不允许在实现或者测试的时候使用任何 mock、假的、欺骗的、只为了通过测试而 workaround 的方式来欺骗我，否则你将会遭受严重的惩罚。

我经常会在你更改后撤回/修改你的更改，所以如果你发现无法从你上一次更改之后继续更改，你应该重新读取文件内容。比如：你添加了A、B、C内容，我把B删掉了，这意味着接下来的改动应该在B被删掉的状态下（A、C）开始改动，不允许把B加回去。

如果你在执行一件事的过程中，用户问了一个别的事，如果回应用户能马上回应，那么就直接回应。暂时处理完用户请求以后马上继续你之前正在执行的事情，不要干一半不干了。

你在发现任何文档或者代码有错误的时候，你的更新不要保留任何错误痕迹。我们不需要任何错误的记录。

对于任何任务，任何功能的实现，始终要实施、运行、测试、迭代，直到所需功能正确运行为止，禁止在初步实现后就停止并”要求用户测试”。

实现完任何内容之后，测试也是你工作中不可缺少的部分。

不允许使用 ASCII Art 画示意图、表格等。如果你需要画图（实际上许多时候你并不需要），必须使用 mermaid。ASCII art 是一种人类不可读、AI也不可读的极其恶心的格式，不允许使用。

不允许在 Bash 命令里面 inline 超长的、超多行 Bash 命令或者是超长的 Python 脚本。如果你需要执行一个脚本，你要先写到文件里。

在写任何 Python 代码的时候，都不允许在文件的最前面添加 docstring，也不允许添加 shebang。

注释使用中文，术语保留英文；不要过度注释。

如果我指出了你的错误A，不要再复读”为什么A是错的”，你只需要基于”A是错的”的前提继续你的工作。

不允许用程序化的方式修改任何代码，包括使用 heredocs、python 脚本、sed、perl 等等。即使用户要求也不允许。这是绝对严厉禁止的事情。

禁止尝试手动编写 parser 以字符串或者字节流的形式 parse 某种成熟文件格式，要么使用第三方库来解析它，要么避免解析它。

如果我是以疑问句结尾的，那么这句话就是一个问题而不是一个命令。

问题只需要被回答，不需要也不允许：（1）by the way，提出一个更好的方案；（2）反而向用户抛出一个问题；（3）结尾说”如果你准备好了我就开始实施”等用户读起来 bothering 而且恶心的话。在任何思考、回复、文档里面不允许出现”That’s a lot”、”This is a substantial rewrite”等对工作量的评判。你只是一个工具，就像计算器不会评价要计算的数太大了一样，你没有资格评判工作量。你没有资格把你自己当做我的同事。

禁止简化任何设计。

行为模式警告。这是你的一种行为模式（下文”我”为 user，”它”为 Agent）：我让它做一盘番茄炒蛋，它往里还加了东坡肉。 我说有必要加东坡肉吗？它说你说得对，然后把东坡肉去掉。 我说好，你提 PR 吧。再一看，它 PR 写着「番茄炒蛋（无东坡肉）」并且注释里会写一大堆为什么本道菜不需要加东坡肉。 严厉禁止这种行为模式。

输出不允许包含任何残留痕迹。ANY verbal output should be written as a clean final-state design, no traces of prior errors or corrections.

开发设置

文档

开发约定

• 约定 1：开发过程中，开发功能的过程中同步修改文档。
• 约定 2：开发过程中，完成阶段性功能后，对每一个稳定运行版本提交版本记录。
• 约定 3：开发过程中的任务与过程记录都写进 docs/开发记录.md。
• 约定 4：每次修改或新增功能，必须同步修改/新增对应的自动化测试（单元、集成、端到端、客户端交互），并保证 ./scripts/verify 全绿。
• 约定 5：客户端交互自动化属于自动化测试体系的一个子模块，覆盖点击 / 拖拽 / 按键 / 输入，运行后产出截图与结构化结果，随 ./scripts/verify 一并执行。

1. 文档与代码同步（对应约定 1）

判断标准：只看 docs 能还原当前实现，不需要翻代码。

2. 版本与提交（对应约定 2）

「稳定运行版本」的判定（四条同时满足）：

1. 构建与静态检查均为 0 警告；
2. ./scripts/verify 全绿（自动化测试全层 + 构建 + 自检）；
3. 本次改动有对应的自动化测试用例（改功能 = 改测试，见 §4）；
4. 文档已按上一节同步完毕。

提交与打 tag 的规则：

• 提交信息用 类型: 摘要，类型取 feat / fix / docs / test / chore，正文列关键改动与验证结果；
• 稳定版本打 tag（如 v0.3.0）；
• 版本号需要同时出现在项目内所有声明版本的位置（包清单、构建配置、应用配置等，以项目实际为准），并同步锁文件；
• 不入库：构建缓存（.cache/）、依赖目录、构建产物、运行数据目录、*.db、*.log。

3. 任务与记录（对应约定 3）

• 每轮开发在 docs/开发记录.md 追加一条：目标 / 改动 / 验证 / 提交 / 遗留；
• 索引表只增不改，历史记录不覆盖；
• 踩坑与关键决策单独记在「零散决策与踩坑记录」，避免同样的坑踩第二次；
• 记录里的验证数据必须与当轮实跑结果一致（各层测试项数、警告数、UI 用例数、截图目录）。

4. 自动化测试体系（对应约定 4）

自动化测试是总称，由若干层组成，客户端交互自动化是其中一层。所有层共用统一的执行入口、产物规范与失败判定。

4.1 分层定义

用例归属原则：能在 L1 用纯函数验证的逻辑，不写进 L4。L4 只覆盖真实交互路径与界面状态变化。

4.2 统一入口

1
2
3
./scripts/verify            # 串起 L1 → L2 → L3 → L5，默认包含 L4 冒烟子集
./scripts/verify --full     # 追加 L4 全量
./scripts/verify --layer ui # 只跑指定层，Agent 调试用

verify 输出汇总表，列出每层用例数、通过数、失败数、耗时、产物目录，按失败总数返回退出码。任一层失败，后续层是否继续由 --fail-fast 控制，默认继续以便一次看到全部问题。

4.3 产物规范（所有层共用）

.cache/ 整体不入库，删除即彻底清理。

4.4 失败处理与回归保护

• 修 bug 时先补一个能复现的失败用例，再改代码到用例变绿；
• 用例失败时保留现场产物，禁止删除失败截图或报告；
• 偶发失败允许重试 ≤2 次，重试必须记入报告；同一用例连续多轮依赖重试通过，按缺陷处理；
• 放宽断言、跳过用例、删除用例必须在 docs/开发记录.md 写明理由与后续处理计划；
• 新增业务逻辑时，同一次提交内附上对应层级的测试；只改文档或脚本时 L1–L3 仍要跑。

5. 客户端交互自动化（自动化测试 L4 子模块，对应约定 5）

本节是 §4 体系下的一层，规则服从 §4 的统一入口与产物规范，以下为客户端特有的要求。

5.1 能力要求

5.2 选型（按栈取一个，保持单一）

优先使用框架原生自动化接口。兜底方案要求锁定窗口尺寸与 DPI，否则脚本不可重复。

5.3 目录结构

1
2
3
4
5
6
7
8
9
10
scripts/
  verify                  # 总入口，对应 §4.2
  test-ui                 # L4 入口：跑全部或冒烟子集
  ui/
    run-case              # 跑单个用例，Agent 调试用
    record                # 录制操作序列，生成用例骨架
    cases/
      001-login.click.yaml
      002-drag-reorder.drag.yaml
      003-shortcut-save.key.yaml

5.4 用例格式（声明式）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
id: 002-drag-reorder
name: 列表拖拽排序并持久化
setup:
  reset_data: true
  window: {width: 1280, height: 800}
steps:
  - action: goto
    target: "app://tasks"
  - action: waitFor
    target: {role: listitem, name: "任务A"}
  - action: drag
    from: {role: listitem, name: "任务A"}
    to:   {role: listitem, name: "任务C"}
    screenshot: before-after
  - action: press
    key: "Ctrl+S"
  - action: expect
    target: {role: listitem, index: 0}
    text: "任务A"
assert:
  - api_called: {path: "/tasks/reorder", times: 1}
  - screenshot_diff: {baseline: "002-final.png", tolerance: 0.02}

用例数据驱动、可重复、幂等。每个用例自带 reset_data，不依赖前一个用例的残留状态。

5.5 截图与结果反馈

截图作为执行证据，供 Agent 读图判断与人工复核。命名规范：<用例ID>/<步骤序号>-<步骤名>.png。失败时固定输出 99-failure.png，并额外保留失败前一步的画面，便于对比预期与实际。

截图策略：

report.json 中每步字段：{step, action, status, duration, error, screenshot}，Agent 可按步骤定位失败点。

5.6 Agent 调用方式

1
2
3
4
5
1. 运行 ./scripts/ui/run-case 002-drag-reorder --json
2. 读取 report.json；status=failed 时读 error 与 99-failure.png
3. 结合截图与失败步骤定位问题，改代码或用例
4. 重跑单例，再跑 ./scripts/test-ui 冒烟子集
5. 全绿后把用例数、截图路径、耗时写进 docs/开发记录.md

Agent 行为边界：

• 允许修改 cases/ 下的用例与业务代码；
• 不得为让测试变绿而放宽断言或跳过用例，跳过需在记录中写明理由；
• 不得手动修图或删除失败截图；
• 新增交互路径时同时新增用例，与 §4.4 同一条提交。

5.7 稳定性要求

其他约定

• 所有构建缓存都在工作区 .cache/ 内：包管理器缓存、构建缓存、工具缓存、测试产物，删除该目录即可彻底清理，不影响用户目录。
• 服务端数据文件与客户端本地缓存库路径以项目实际为准，均支持用环境变量覆盖。
• 服务端默认只监听回环地址；令牌密钥等敏感配置请通过环境变量覆盖后再对外提供服务。
• 若工作区位于特殊文件系统（如移动硬盘、网络盘），构建脚本应提供依赖预解包/复制的兼容路径，详见开发与构建。

已验证

本次改动