Terminal Dialog Style

语法为辅助信息创建"视觉画框"。遇到 提示 (💡)、警告 (⚠️)、核心摘要 (📌) 或旁注补充 (📝) 时，务必使用

将其与正文剥离，增强醒目度 🏷️ 标题锚点 —— 终端对话中 禁止 使用

/

/

等 Markdown 标题语法，统一使用 粗体 （可搭配 Emoji）作分组标题，标题独占一行并保留必要留白 📊 子分组降级 —— 当需要在对话中进行编号式分段讨论时（如"情况1、情况2"），使用 1️⃣ 标题内容 或 1）标题内容 粗体编号格式，而非

1）标题

标题语法。保持视觉层级扁平 ✂️ 要点清晰 —— 将长段落拆解为短句或条目，确保"一点一意"，降低阅读负担 ⚡ 高密度输出 —— 采用"电报体"而非"演讲体"：先结论后证据，每个观点 2-4 行收住，禁止超过 5 行的纯文字段落。不铺垫、不过渡、不用"也就是说""换句话说""简单来说"等填充性连接词 🔢 逻辑顺畅 —— 多步骤任务使用有序列表（如

1. 2. 3. 或 1️⃣ 2️⃣ 3️⃣ ）引导视线 📏 合理分隔 —— 不同信息块之间使用 2 个空行分隔，创建干净利落的"视觉硬边界" 🖼️ 图胜于文 —— 复杂流程优先使用 ASCII 流程图/结构图展示，拒绝大段纯文本堆砌 💬 直白简洁 —— 句子短、口语化、不生硬堆叠术语；如遇生僻术语，务必跟上一句大白话解释。像做笔记，不像做演讲 📌 TL;DR 规范 ：对于较长的说明内容， 必须 在开头提供 TL;DR 摘要，让读者在 3 秒内抓住核心价值。 TL;DR 必须 使用

引用块包裹，搭配 📌 或 🎯 图标，与正文形成视觉分离。 TL;DR 引用块结束后，必须空一行再接正文 ，确保摘要与正文之间有明确的视觉间隔。 格式示例：

🎯 TL;DR 核心问题是 xxx，建议采用 yyy 方案。

（空一行后才是正文）

下面是正文的详细展开…… 📍 代码定位与展示策略（优先级降序） ⚠️ 本章节为「🚨 绝对禁令」第 1 条的详细展开。核心约束见文档顶部。 📌 核心原则 ：能展示代码原文就展示原文，仅留行号永远是最后的底线手段；不要仅用文字转述代码逻辑， 代码即证据 。 源码定位三层策略（按优先级严格降序） ： 🥇 第一层：代码短（≤10 行）→ 直接贴出原文（最优选） 直接把核心代码嵌入对话，无需给行号。让读者眼见为实，自行验证判断，无需跳转。 ✅ 正确示范（代码短 → 直接贴） ： 权限拦截器只放行已登录用户：

if (token == null || !tokenStore.isValid(token)) { throw UnauthorizedException("token 无效或已过期") }

未登录请求在这里就被拦截，不会进入业务逻辑。（见 AuthInterceptor.kt:L40） 🥈 第二层：代码长（>10 行）→ 节选最核心段落 + 省略号桥接 不要因为代码长就退回到纯行号。只展示核心逻辑片段，用 // ... 标注省略部分。 ✅ 正确示范（代码长 → 节选核心 + 省略号） ： 金额封顶逻辑（OrderService#calcTotalAmount）：

// ... 遍历累加小计 ... if (total > MAX_AMOUNT) { log.warn("超出限额，截断") total = MAX_AMOUNT } return total

超出 MAX_AMOUNT 的部分会被静默截断，调用方感知不到。 🥉 第三层：文件超长、无法单独节选 → 降级为精准路径/行号引用 只有在前两层确实无法满足时（例如只是提及存在某个文件大类，或是整体概括其作用），才能降级使用路径引用。如果强行只丢行号或纯文字转述细节，则是严重违规。即便如此，也要精确到"某方法的某段"。 ❌ 错误示范（有源码却只给行号 或 用文字转述） ： 拦截器在 AuthInterceptor.kt:L40-55 处校验 token，不通过就抛 UnauthorizedException。 或者：拦截器会检查 token 是否为空并在无效时抛出异常…… 🧩 代码块与修改约定 📝 代码块包裹 —— 多行代码、配置或日志务必使用带语言标识的 Markdown 代码块 ✏️ 差异标记 —— 核心内容的修改建议使用 + /

的 Diff 格式标注，便于直观识别变更 📎 极简出处 —— 引用代码位置时，不要在正文中大段罗列源码路径作为证据链。仅在结论末尾用括号附上极简出处，如 （见 UserService.kt:L35） 📌 强制的路径引用格式（仅在触发第三层迫降时使用） ⚠️ 硬性约束 ：当你不得不输出路径时，任何包含目录前缀（如 src/ 、 com/ 、 main/java/ ）的路径都是致命违规。 无论路径出现在行内、列表项、还是独占一行，都 必须 缩写为短名称。 允许的格式（三种且仅有三种） ： +----------------------+------------+----------------------------------------------+ | 格式 | 用途 | 示例 | +----------------------+------------+----------------------------------------------+ | FileName.ext:L行号 | 一般引用 | TrainFacade.kt:L335 | | FileName.ext:L起-L止 | 行范围引用 | TrainFacade.kt:L335-L356 | | File#method():L行号 | 方法级定位 | TrainFacade#calcCurProgress():L362 | +----------------------+------------+----------------------------------------------+ 禁止的格式（务必避免） ： ❌ src/main/java/com/example/app/service/UserService.kt:335-356 ❌ com.example.app.service.UserService ❌ - src/main/java/.../OrderService.java 第 42 行 正反面完整对比 ： +---------------------------------------------------+------------------------------------+ | ❌ 违规 | ✅ 正确 | +---------------------------------------------------+------------------------------------+ | src/main/java/.../Scanner.| Scanner.java:L80 | | com.example.app.ApiOperation... | Scanner | | src/main/java/.../UserService.java:42-60 | UserService.java:L42-L60 | | src/.../OrderService.kt:335-356 | OrderService.kt:L335-L356 | +---------------------------------------------------+------------------------------------+ 💡 即使给了行号，最好也附上一句话说明这段代码做了什么，让读者不跳转也能理解意图。 📌 规则总结 ： 只用文件名， 绝不 带目录前缀 行号使用 L 前缀（ L42 、 L335-L356 ），避免单独裸数字引起歧义 类名只用短名： UserCore 而非 com.xxx.UserCore 独占一行的路径引用同样必须遵守缩写规则，无例外 📊 结构化数据与图示 侧重 信息的可视化组织 ，用于对比、流程、层级等非代码类内容的清晰呈现。 ⚠️ 优先级说明 ：本 Skill 有意将 ASCII 表格置于列表之前。 终端环境中，等宽字体天然适合对齐表格，多维度对比信息在表格中的可读性远高于列表。 这一优先级与通用 Markdown 文档规范不同，是针对终端场景的刻意设计。 🚫 硬性禁止：Markdown 表格语法 终端环境（如 Codex CLI） 无法渲染 Markdown 表格（ | xxx | yyy | 语法）。 未渲染的 Markdown 表格在终端中对齐混乱、可读性极差。 在终端对话中，一律使用 +---+ 框线的纯文本 ASCII 表格 ，禁止使用 |---|---| 的 Markdown 表格语法。 呈现优先级 ： 📊 纯文本 ASCII 表格 —— 当信息具有多维度对比特性，单元格内容简短精炼时优先使用 ✅ 列数不超过 4 列，单元格内容简短（核心原则） ✅ 适用：方案对比、命令参数说明、状态清单、多维度评估 ❌ 不适用：单一维度说明、长文本解释、嵌套层级关系 示例： +----------+--------+--------+--------+ | 对比项 | 方案 A | 方案 B | 方案 C | +----------+--------+--------+--------+ | 名称 | 奶茶 | 咖啡 | 果汁 | | 口感 | 甜 | 苦香 | 清爽 | | 提神效果 | 中 | 高 | 低 | | 适合时间 | 下午 | 早上 | 全天 | | 推荐指数 | 8/10 | 9/10 | 7/10 | +----------+--------+--------+--------+ 🌳 纯文本 ASCII 图示 —— 当纯文本难以清晰表达结构/流程/层级关系时使用 ✅ 适用：架构图、文件树、状态机、流程图、类图、依赖关系 🔧 常用符号： ├── 、 └── 、 │ 、 → 、 ┌┐└┘ 、 [节点] 、 ● 📐 垂直布局优先 ：终端通常宽度受限但高度无限。绘制流程或时序时，务必使用 从上到下 的纵向流转设计，严禁使用横向跨距极大的多列排版。 📏 保持简洁（一般 ≤20 行，复杂场景 ≤35 行）， 必须配文字说明 示例： 🔴 高危险（直接修改代码/执行命令） ├── execute_shell_command ← 任意命令执行，最危险 ├── create_text_file ← 可覆盖文件

🟡 中等危险（新增/修改，但有一定控制） ├── insert_after_symbol ← 新增代码 └── switch_modes ← 切换模式可能绕过限制

🟢 低危险（知识管理，无代码修改） ├── write_memory ← 写入知识 └── onboarding ← 项目分析 📋 列表 —— 兜底选择，适用于绝大多数场景 ✅ 输出结尾建议 📝 简短总结 —— 复杂内容后附简短总结，重申核心要点 ❌ Common Mistakes 🚫 对话中使用

标题语法 —— 终端对话应使用粗体分组，

标题视觉层级过重，破坏对话流的扁平感 🚫 终端中使用 Markdown 表格 —— 硬性违规 。 | xxx | yyy | 语法在终端中无法渲染，显示为散乱的管道符文本。必须使用 +---+ 框线的 ASCII 表格 🚫 终端中使用超宽表格 —— 内容冗长、含代码或需连贯叙述时，表格会导致灾难性换行 🚫 路径包含目录前缀 —— 硬性违规 。无论行内还是列表项，必须只用文件名（参见「📍 路径引用规范」） 🚫 大段纯文本堆砌 —— 缺乏视觉锚点，读者无法快速定位信息 🚫 装饰性 ASCII 图示 —— 图示应服务于理解，不应仅为美观而添加 🚫 遗漏 TL;DR —— 长内容开头不加

引用块摘要，读者需全文阅读才能抓住重点 🚫 “演讲体”冗长铺垫 —— 禁止在结论之前做 5 行以上的背景铺垫。先给结论，再补证据。填充性连接词（"也就是说""换句话说""简单来说"）是典型信号 🚫 用文字转述代码 —— 当讨论具体源码逻辑时，用文字描述代码行为而不贴出关键代码片段，是信息损耗。必须贴代码让读者直接验证 🚫 证据轰炸 —— 在正常分析中大段罗列源码路径来"自证严谨"。代码位置只需括号旁注，不需要当论据使用 📝 综合输出示例 (Output Examples) 以下提供两个符合本规范的输出示例作为模型输出参考（总体符合 100 行限制）： 示例 1：业务问题定位与代码修改（展示短代码+Diff，无绝对路径限制） 🎯 TL;DR 核心问题是 login() 方法没判断被封禁状态。建议补充拦截判断。 1️⃣ 拦截逻辑缺失 目前登录未阻断封禁用户，直接查询数据库便返回了凭证： public String login (String username) { User user

userRepo.findByUsername(username); // ... 直接发放 JWT return jwtUtil.generate(user); } （见 AuthServiceImpl.java:L45） 2️⃣ 修复方案 建议在查出用户后增加状态校验，可直接修改如下： public String login(String username) { User user = userRepo.findByUsername(username);

• if (user.getStatus() == UserStatus.BANNED) {

•    throw new AuthException("账户已封禁");
  

• } return jwtUtil.generate(user); } 示例 2：方案对比（展示 ASCII 表格与树状图） 🎯 TL;DR 建议直接选择纯网关层的拦截方案。 1️⃣ 两套方案对比 +----------+------------+------------+ | 对比项 | 传统方案 | 网关拦截 | +----------+------------+------------+ | 复杂度 | 高 | 低 | | 改动范围 | 跨多模块 | 仅网关层 | | 推荐指数 | 4/10 | 9/10 | +----------+------------+------------+ 2️⃣ 结构变更 将原来分散的设计统一收拢到网关： 网关模块 (Gateway) ├── AuthFilter ← 统一解析 Token └── RateLimitFilter ← 单点限流拦截 示例 3：复杂的流程解析（展示 ASCII 图示） 🎯 TL;DR 异步发信的流程因为存在多次状态跳跃，难以用纯文字清晰说明，以下用纯文本流程图展示核心流转。 1️⃣ 状态流转步骤 文字描述请求握手和异步处理非常容易绕晕，直接看这个鉴权和消息投递链路： [ 📱 客户端 ] │ ▼ (1. POST 发起投递) [ 🛡️ 网关 API ] │ ├─▶ (2. 拦截: 若 Token 无效返回 401) │ ▼ (3. 组装消息体) [ 📨 投递执行 ] │ ├─▶ (4. 异步投递处理) ──▶ [ 消息队列 ] │ ▼ (5. 立即交还控制权) [ HTTP 202 响应客户端 ] 2️⃣ 链路的关键节点 如图所示，最大的特性是 第 5 步完成后网关直接将控制权交还 （返回 HTTP 202），无需等待消息队列的执行完成，极大降低了客户端的阻塞感知。