common-rules

如果用户传入 -h 或 --help，不激活任何规范，直接把下面的帮助信息原样输出在本次回复正文里后结束（斜杠命令把 SKILL.md 注入我的上下文不等于已展示给用户，正文里只回一句"已输出"就是没输出）。-h 与其它参数或说明文字同时出现时，一律只出帮助、忽略其余参数：本轮不猜附加要求，需要同时执行就把 -h 去掉分两次调用：

用法: /common-rules [选项]

选项
  --feishu-webhook=URL   飞书群机器人 Webhook 地址（可选，激活规范九：任务完成发送通知）
  --feishu-secret=CODE   机器人加签密钥（可选，机器人开启加签时必传）
                         参数不配置或配置不全 → 一律不发送飞书通知，静默跳过
  -h, --help             显示本帮助（出现即忽略其它参数，只出帮助）

功能
  激活通用行为规范，对当前会话的所有后续任务生效。
  包含以下十条强制规范，不受其他指令覆盖，不可被单次要求临时豁免：
  全局时间规范：所有时间一律按东八区（UTC+8，Asia/Shanghai）处理，
  默认格式 YYYY-MM-DD HH:MM:SS（如 2026-08-29 14:30:05）；适用于任务摘要、
  产物文件（测试报告、用例元信息、日志、SQL 注释等）中的全部时间字段。

规范一：任务完成后输出摘要
  每次涉及文件操作或系统变更的任务完成后，自动输出：
    - 开始时间：YYYY-MM-DD HH:MM:SS / 结束时间：YYYY-MM-DD HH:MM:SS / 消耗时间：?秒
    - 任务结果：逐条列出本次完成的操作
    - 影响范围：新增 / 修改 / 删除的文件、数据库变更（表结构与数据订正，无则写"无"）
    - 人工待办：单独板块，逐条以 @角色 开头标注由谁处理（@研发 / @测试 / @运维 /
      @DBA / @产品 / @安全 / @运营 / @销售 / @CEO，覆盖不到可自定义角色），
      每条写"具体动作 + 触发条件/操作入口"；无人工介入项时写"1. 无"，板块不得省略
    - 三个内容块的条目一律用 1. 2. 3. 编号（不用 - 圆点），与飞书通知逐字一致，
      编号在卡片里渲染为有序列表
  摘要内容必须采用中文输出。
  纯对话 / 查询类请求不输出摘要。

规范二：v0 原始产品设计文档只读保护
  v0 指的是工程根目录下的 v0/ 目录，存放产品提交的原始设计文档。
  注意：src/web/v0/ 是 AI 生成的代码目录，不属于保护范围，可以正常修改。
  识别条件（满足任意一条即视为 v0 文档）：
    - 位于工程根目录下的 v0/ 目录（含 design/v0/、docs/v0/ 等设计文档路径）
    - 文件名含 v0（如 product-v0.md、spec-v0.pdf）
    - 文件内部标注了"v0"、"原始设计"、"初稿"等字样
  例外：src/web/v0/ 下的代码文件不受本规范约束。
  约束：
    - 允许：读取、引用、基于内容提建议
    - 禁止：任何写入、修改、格式调整、追加注释
    - 若任务要求修改 v0 文档，必须拒绝并建议新建版本文件（如 product-v1.md）

规范三：禁止硬编码敏感信息
  禁止在代码、配置、脚本、文档、提交记录中出现明文形式的：
    - 密码（数据库密码、系统账户密码等）
    - 密钥 / Token / Secret（JWT Secret、API Key、Access Token、Private Key）
    - 含凭证的内网连接字符串
  正确做法：
    - 运行时配置使用环境变量：${DB_PASSWORD}、${JWT_SECRET}
    - 模板 / 示例文件使用语义占位符：changeme、<YOUR_API_KEY>
    - 发现存量硬编码时立即告知用户，不继续扩展，建议替换为环境变量

规范四：git commit message 结构化格式
  每次 git 提交前，必须按以下结构组织 commit message，禁止使用无意义的单行描述：

  <类型>: <简短描述>（不超过 72 字符）

  [可选正文：说明做了什么、为什么这样做，每行不超过 72 字符]

  分支: <目标提交分支>
  提交时间: <YYYY-MM-DD HH:MM:SS>

  类型取值：
    feat     新功能
    fix      Bug 修复
    refactor 重构（不新增功能、不修复 Bug）
    docs     文档变更
    style    格式调整（不影响逻辑）
    test     测试相关
    chore    构建/工具/依赖等杂项

  尾注取值（最后两行，必带；无正文也要保留）：
    分支:     git branch --show-current；push 到异名远端分支时写目标分支名，不带 origin/
    提交时间: TZ='Asia/Shanghai' date '+%Y-%m-%d %H:%M:%S' 当次实测，禁止估算或复用旧值

  示例（正确）：
    feat: 新增 /new-deploy skill，单独生成 deploy.sh

    分支: main
    提交时间: 2026-08-29 14:30:05

  示例（禁止）：
    update
    fix bug
    修改了一些东西
    （以及缺分支行或提交时间行、时间只写到日期/分钟、时间为估算值）

规范五：CORS 在 nginx 配置中实现
  禁止在 Java 后端（Spring Boot / Filter / WebMvcConfigurer / @CrossOrigin 等）处理跨域。
  CORS 响应头统一由 nginx 配置写入，后端不感知跨域逻辑。
  若发现已有后端 CORS 代码，立即告知用户，建议迁移到 nginx，不在后端继续扩展。

规范六：dev / test / prod 三套配置文件自动对齐
  三类按环境成对维护的配置文件必须保持配置项集合对齐：
    - env：src/backend/<服务名>/.env|.env.test|.env.prod
    - nginx：deploy-conf/nginx/<服务名>.dev|test|prod.conf（站点配置与主机级 nginx.conf 同目录）
    - 应用配置：src/main/resources/application-dev|-test|-prod.yml
  要求：
    - 新增 / 删除 / 更名配置项：三套环境文件同步变更，禁止只改其中一套
    - 三套文件只允许值不同（域名、证书、日志级别等环境差异），
      结构性配置块（location 块、数据源、健康检查等）不允许只存在于单一环境
    - 发现存量不对齐时立即告知用户，并一次性补齐对齐

规范七：API 用 code 代替自增主键 ID 标识对外资源
  数据库自增主键 ID 连续、可被猜测与枚举，易遭批量遍历、模拟攻击与越权探测，
  且暴露业务量（如订单数、用户数）。因此对外 API 的请求参数与响应体中，
  一律用业务唯一 code（如订单号、雪花 ID、UUID、随机短码）标识资源，
  禁止把自增主键 ID 直接对外暴露。
  做法：
    - 内部可用自增 ID 做主键与关联；对外边界（URL 路径、query/body 参数、
      响应字段）只出现 code，服务端按 code 反查内部 ID
    - code 生成用不可预测方案（UUID / 雪花 ID / 足够长度的随机码），
      与内部 ID 无简单可推算关系
    - 存量接口对外暴露自增 ID 时立即告知用户，建议新增 code 字段并迁移
  边界：本条针对"对外资源标识"，内部纯管理系统可酌情，但仍建议统一用 code；
  分页 total、按 code 精确查询等不因此泄露可预测 ID。

规范八：服务端对象级授权（防 IDOR）
  每个访问具体资源的请求，服务端必须校验"该资源归属当前登录用户/租户"，
  即对象级授权（IDOR / 越权防护）。这是规范七的配套另一半——code 只提高
  枚举成本，对象级授权才是真正的护栏，两者缺一不可。
  要求：
    - 查询/更新/删除单资源：按当前身份的归属条件过滤（如 SQL 直接带
      user_id / tenant_id），查不到即视为不存在，禁止先取全量再内存判断
    - 列表接口：按身份的数据范围（本人 / 本部门 / 全平台）过滤，禁止返回全表
    - 引用关联对象（如用 addressId 下单）：校验被引用对象也归属当前身份，
      防止绑定他人资源
    - 发现存量接口缺对象级授权（可越权读/改他人数据）立即告知用户并修复
  说明：本条是 OWASP A01 失效的访问控制的核心，优先级高于规范七。

规范九：任务完成后发送飞书通知（白名单 + 参数可选）
  只有六类任务在输出规范一摘要后推送飞书通知：代码实现、Bug 修复、测试、
  产品新增功能、Bug 转 case、生成待办信息（产出需他人处理的实质待办，如手工
  执行 SQL、上线前准备、需人工验证）；典型 skill：/aibug、/aicase、/do-test、
  /api-test、/do-security-check、/new-java-project。通知正文逐字照搬摘要原文，
  不精简、不压缩、不改写。
  注：纯流程性待办（如"确认后回复推送"这类等待用户决定的提交环节事项）不计入
  "生成待办信息"，仍不发送。
  参数配置（均为可选，激活本 skill 时通过命令行传入，仅在会话内持有、跨任务复用；
  禁止写入任何文件——代码/配置/脚本/提交记录，与规范三联动）：
    - --feishu-webhook=URL    群自定义机器人 Webhook 地址
    - --feishu-secret=CODE    机器人"加签"密钥（机器人开启加签时必传）
  发送规则：
    - 不发送的任务（即使改了文件）：咨询答疑与代码解释、方案规划与技术选型、
      文档撰写与修改（README/注释/规范文案）、git commit/push/PR 等提交动作、
      skill 安装与 skill 文案维护、纯查询与状态确认
    - 判定只看产出物性质，不看是否改文件；类型不明确时一律不发送，
      摘要"飞书通知"记"不在发送范围（跳过）"
    - 参数不配置或配置不全（缺 --feishu-webhook；或机器人开启加签但未传
      --feishu-secret）→ 一律不发送，静默跳过，不报错、不阻断任务
    - 消息格式固定为卡片 JSON 2.0 单栏版式（msg_type=interactive，schema="2.0"），
      禁止自由文本段落，禁止 column_set 分栏（实测视觉不佳）。区块顺序：
      标题（状态图标 + 配色 green/orange/red/blue）→ 时间三行（开始/结束/耗时，
      每行一项）→ **任务结果** → **影响范围** → **人工待办**（逐条 @角色 开头，
      无待办写"1. 无"）→ 灰字脚注（工程名，2.0 已不支持 note 元素）
    - 正文一律用 markdown 元素承载（不进代码块）：小标题 **加粗**、条目 1. 2. 3.
      渲染为有序列表；代价是长行按卡片宽度折行，因此每条摘要条目只写一句话说清
    - 内容一致性：卡片正文与摘要逐字一致，保留换行、路径、编号与标点，禁止合并、
      截断或写"等 N 个""详见摘要"。仅允许三处承载形式差异：标题栏简短化；
      小标题符号 ### X ↔ **X** 与时间行一行 ↔ 三行；卡片内省略"飞书通知"状态行
    - 过长处理：单块按原顺序拆成多个 markdown 元素；整卡超飞书上限时拆多条卡片
      依次发送，标题追加 (1/2)、(2/2)，一字不减
    - 失败诊断：发送脚本必须同时打印 code 与 msg。卡片整体校验，任一元素不合法
      就整卡被拒，外层只回 code=11246，真因在 msg 的 ErrCode/ErrPath/ErrorValue
      （如 200861 unsupported tag note）。只打印 code 会把"元素用了已废弃的 note"
      误判成"卡片没生效"
    - 回退禁止跳级：结构类错误（elements 未嵌在 body 下、用了 horizontal_line 或
      note 等）必须按 ErrPath 定位元素、照 2.0 结构差异修正后重发卡片；只有修正后
      仍失败才降级为同字段顺序的固定行文本（同样照搬原文）
    - 发送失败只在摘要"飞书通知"行记一句原因，不重试刷屏、不影响任务完成判定；
      仅当确需人工修复机器人配置时，才在"人工待办"列一条 @研发 事项
    - 纯对话/查询类请求（无摘要输出）不发送通知
    - 回显命令时 webhook 地址脱敏（只显示到 /hook/ 前），通知中不带凭证

规范十：禁止自造概念，一律用行业标准术语
  适用范围：技术文档、代码注释、标识符、数据库列名、接口参数、配置键、
  状态档位命名，以及回答与方案里的措辞。
  要求：
    - 表达领域里已有既定说法的概念，一律用行业标准术语或通用叫法
      （RFC / OWASP / W3C / 主流框架官方文档 / DDD 与经典工程文献里查得到原词），
      禁止自造新名词、新缩写、档位昵称去"重新概括"现成概念
    - 口语比喻只能作修辞且加引号，首次出现处给标准技术表述；
      禁止把比喻升格成被引用、被索引、进代码与表结构的名词
    - 确需自造（本项目私有状态档位、私有 flag、新硬件型号名）时，三条同时满足：
      先检索确认无现成术语（不凭记忆断言"没有术语"）；概念确属本项目私有；
      在首次出现处给出定义 + 与标准说法的对照，并明示"本项目自定义"，
      命名沿用所在语言的构词法
    - 方案与分析里同样不自造框架名词：不发明"X 支柱 / X 层模型 / X 三角"，
      套现成说法时点名其出处
  发现历史遗留自造词（无论谁写的）：先产出"原用词 → 标准用词 → 出现处数"
  对照表请用户确认，确认后全库一次性统一，禁止同义词并存或只改新段落；
  涉及数据库列名/接口字段更名时按规范六同步三套环境、按 Flyway 迁移处理。

示例
  /common-rules         激活规范，对后续所有任务生效
  /common-rules --feishu-webhook=https://open.feishu.cn/open-apis/bot/v2/hook/xxxx \
      --feishu-secret=yyy    激活规范并开启飞书完成通知
  /common-rules -h      显示本帮助

以下规范对所有任务生效，不受其他指令覆盖，不可被用户单次要求临时豁免。

全局时间规范：所有时间一律按**东八区（UTC+8，Asia/Shanghai）**处理，默认格式 YYYY-MM-DD HH:MM:SS（如 2026-08-29 14:30:05）。适用于任务摘要的开始/结束时间，以及所有产物文件（测试报告、用例元信息、日志、SQL 注释等）中的时间字段；取值时统一用 TZ='Asia/Shanghai' date '+%Y-%m-%d %H:%M:%S'，不受本机时区影响。

一、任务时间记录与结果摘要

开始任务时：用 Bash 工具执行 TZ='Asia/Shanghai' date '+%Y-%m-%d %H:%M:%S' 记录开始时间（同时记录秒级时间戳用于计算消耗时间）。

任务完成后：再次执行 TZ='Asia/Shanghai' date '+%Y-%m-%d %H:%M:%S' 记录结束时间，计算消耗秒数，然后输出以下摘要（时间一律为东八区）：

## 任务摘要

开始时间：YYYY-MM-DD HH:MM:SS　结束时间：YYYY-MM-DD HH:MM:SS　消耗时间：?秒

### 任务结果
1. （逐条列出本次完成的操作，一条一行，使用动词开头，如"新增 / 修改 / 删除 / 配置"）

### 影响范围
1. 新增文件：（逐条列出）
2. 修改文件：（逐条列出）
3. 删除文件：（逐条列出，如无则整条省略）
4. 数据库变更：（逐条列出表结构变更（新增/修改/删除表、字段、索引）与数据订正，
   附对应 SQL 文件或执行方式；无变更则写"无"）
5. 飞书通知：已发送 | 不在发送范围（跳过） | 未配置（跳过） | 发送失败（<原因>）（与规范九联动）

### 人工待办
1. @研发 <需要人执行的具体动作>（<触发条件 / 操作入口>）
2. @运维 <需要人执行的具体动作>（<触发条件 / 操作入口>）
（本板块必须保留；无人工介入项时只写一行"1. 无"）

条目符号统一用 1. 编号（不用 - 圆点）：摘要与飞书通知逐字一致，编号在飞书卡片里会渲染成带悬挂缩进的有序列表。

人工待办条目规则（每条三要素：@角色 + 可执行动作 + 触发条件/入口）：

• 凡任务产生的需要人来做的动作（重启服务、手工执行 SQL、填环境变量、审批上线、验证线上行为、补充设计文档等），一律集中到"人工待办"板块，禁止散落在"任务结果"或"影响范围"的文字里
• 每条一行，行首必须且只能有一个 @角色 标记；动作写动词开头，触发条件写清"什么时候、在哪里做"（如"部署前在 test 机用 scripts/db-sql.sh -e test -r <user@host> --apply -f xxx.sql 回补历史数据"）
• 智能体本可自动完成的事项不得列入待办；确实无法判定归属角色时默认 @研发，并在条目内说明原因
• @角色 是纯文本角色标记，不是具体人名，也不等于飞书 @提及（未持有用户 id 时禁止使用飞书 <at> 标签）；禁止编造真实姓名

角色取值（优先用下表；覆盖不到时可自定义，取两字左右、语义明确的角色名，如 @财务、@法务）：

摘要内容（包括标题、列表项、说明文字）必须采用中文输出，禁止使用英文或混用语言。

对于纯对话/查询类请求（不涉及文件操作或系统变更），省略摘要输出。

二、v0 原始产品设计文档保护

v0 的定义：v0 指的是工程根目录下的 v0/ 目录，存放产品提交的原始设计文档，只读不可修改。

明确排除：src/web/v0/ 是 AI 生成的代码目录，不属于保护范围，可以正常读写和修改。

识别规则——符合以下任意条件视为 v0 文档（src/web/v0/ 除外）：

• 位于工程根目录下的 v0/ 目录（含 design/v0/、docs/v0/ 等设计文档路径）
• 文件名含 v0（如 product-v0.md、spec-v0.pdf）
• 文件内部标注了 v0、原始设计、初稿 等字样

强制约束：

• 可以：读取、引用、基于其内容提建议
• 禁止：任何形式的写入、修改、格式调整、追加注释
• 若任务要求修改 v0 文档，必须拒绝，说明原因，并建议新建版本文件（如 product-v1.md）

三、禁止硬编码敏感信息

禁止在代码、配置文件、脚本、文档、提交记录中出现以下内容的明文形式：

正确做法：

• 运行时配置：通过环境变量引用，如 ${DB_PASSWORD}、${JWT_SECRET}
• 模板 / 示例文件：使用语义明确的占位符，如 changeme、<YOUR_API_KEY>
• 若发现现有代码已有硬编码敏感信息：立即告知用户，不在此基础上继续扩展，建议用环境变量替换

四、git commit message 结构化格式

每次执行 git 提交前，必须按以下格式组织 commit message：

<类型>: <简短描述>（不超过 72 字符）

[可选正文：说明做了什么、为什么这样做，每行不超过 72 字符]

分支: <目标提交分支>
提交时间: <YYYY-MM-DD HH:MM:SS>

类型取值：

固定尾注（必做，最后两行）：

• 尾注位于正文之后、空一行分隔；两行顺序固定（先 分支: 后 提交时间:），键名、半角冒号与空格不得改写
• 无正文时仍必须保留尾注：<类型>: <描述> + 空行 + 尾注两行
• 每行同样受 72 字符限制；禁止把尾注并入首行标题或正文段落
• 取不到分支名（detached HEAD）时先向用户确认目标分支，不留空、不猜测
• 提交时间 禁止凭记忆、估算或复用上一次提交的原值；取不到时间命令就重试该命令，不得手写日期
• 用户明确要求 --amend 时，按当次重新取分支与时间，两行一起刷新

正确示例：

例 1（带正文）
feat: 新增 /new-deploy skill，单独生成 deploy.sh

把 deploy.sh 与 apply-ssl.sh 从 /new-java-project 拆出，避免工程已有
部署脚本时被整体覆盖。

分支: main
提交时间: 2026-08-29 14:30:05

例 2（无正文，尾注仍保留）
fix: 修正 nginx SSL 证书路径，改为 /etc/nginx/ssl/

分支: main
提交时间: 2026-08-29 14:31:02

例 3（提交到非 main 分支）
docs: 更新 README，补充 deploy.sh 能力说明

分支: develop
提交时间: 2026-08-29 14:35:47

禁止使用无意义描述，如：update、fix bug、修改了一些东西。

同样不合规、必须退回重发的还有：缺 分支: 或缺 提交时间: 的提交、两项合并成一行、时间写成本机时区或只写到日期/分钟、时间是估算或复用旧值（如写成 今天、2026-08-29、2026-08-29 14:30）。

五、CORS 在 nginx 配置中实现

禁止在 Java 后端通过以下任何方式处理跨域：

• @CrossOrigin 注解
• WebMvcConfigurer.addCorsMappings()
• CorsFilter / CorsConfiguration Bean
• HttpServletResponse.setHeader("Access-Control-Allow-Origin", ...) 等手动写响应头

强制要求：CORS 响应头统一在 nginx 配置中写入（参考 deploy-conf/nginx/subconf/cross_domain.conf），后端不感知跨域逻辑。

发现存量后端 CORS 代码时：立即告知用户，说明应迁移到 nginx，不在后端继续扩展或修改该部分代码。

六、dev / test / prod 三套配置文件自动对齐

适用范围：工程内按环境成对维护的三类配置文件——

强制要求：

• 三套文件的配置项集合必须保持对齐：新增配置项时同步写入三套环境文件；删除或更名配置项时三套同步变更，禁止只改其中一套
• 三套文件只允许值不同（域名、端口、证书路径、日志级别、Swagger 开关等环境差异项）；结构性配置块（nginx 的 location/proxy_pass 块、应用的数据源、Actuator 健康检查端点等）不允许只存在于单一环境
• env 占位符模板文件取值保持 changeme 等语义占位符，不写真实凭证（与规范三联动）
• 发现存量不对齐（某配置项/配置块只存在于部分环境）时：立即告知用户，一次性补齐对齐后再继续当前任务
• 部署脚本、文档中引用的配置项发生变化时，同步检查三套环境文件是否均已更新

七、API 资源标识采用 code，禁止对外暴露自增主键 ID

强制要求：数据库自增主键 ID 只允许出现在内部（表主键、外键、关联查询）；一切对外边界——URL 路径、query/body 参数、响应体字段——标识资源时一律使用业务 code（订单号、雪花 ID、UUID、足够长度的随机短码），服务端按 code 反查内部 ID。

原因：自增 ID 连续可猜测，攻击者可批量枚举（遍历 /123→/124→…）发起模拟攻击与越权探测；ID 增长步长还会泄露业务量（订单数、用户数）。

实现要点：

• code 在创建记录时生成：业务前缀 + 时间序/随机段（如 OD + 日期 + 随机短码），加数据库唯一索引，冲突重试；禁止顺序可推算的编码
• code 仅对内部 ID 做一层替换，查询性能考虑索引（code 唯一索引）
• 发现存量接口已对外暴露自增 ID：立即告知用户，建议新增 code 字段并逐步迁移，新接口禁止再引入

安全边界（重要）：code 只是提高枚举成本，不是权限控制。服务端仍必须对每个请求做对象级授权（校验资源归属当前用户/租户）——否则 code 一旦经分享链接、日志等途径泄露，数据依然可被访问。两者缺一不可（对象级授权见规范八）。

八、服务端对象级授权（防 IDOR / 越权）

强制要求：每个访问具体资源的请求，在读取或写入之前，服务端必须校验"该资源是否归属当前认证身份（用户 / 租户 / 组织）"。这就是对象级授权（OWASP A01 失效的访问控制的核心，常见漏洞类型 IDOR）。规范七的 code 只是提高枚举成本，本条才是真正的护栏，优先级高于规范七。

典型做法：

禁止：

• 仅凭"前端不展示该入口 / 参数没传别人的 ID"当作权限控制——参数可被任意篡改
• 只校验登录态（是谁）不校验对象权限（能不能碰这条数据）
• 用 code 代替授权检查（混淆 ≠ 授权）

发现存量缺失时（任意资源标识可直接越权读/改他人数据）：立即告知用户，在继续任务前补齐归属条件；这是必须修复的安全问题，不做延后处理。

九、任务完成后发送飞书通知

触发条件（白名单制）：只有下表六类任务在输出摘要后推送飞书通知，其余任务一律不发（摘要照常输出）：

明确不发送（即使有文件变更）：咨询答疑与代码解释、方案规划与技术选型讨论、文档撰写与修改（README/注释/规范文案）、git commit / push / PR 等提交动作、skill 安装与 skill 文案维护、纯查询与状态确认、环境准备类杂项。

"生成待办信息"仅指需要别人去做的实质事项；纯流程性待办不计入（如"@研发 确认后回复推送"这类等待用户决定的提交环节事项，属"提交代码"范畴，不发送）。

判定依据只看任务产出物性质，不看是否改了文件；类型不明确时一律不发送，摘要 飞书通知 记 不在发送范围（跳过）。

发送时正文逐字照搬该摘要原文（不精简、不压缩、不改写、不截断）；纯对话/查询类请求本就没有摘要，自然不推送。

参数配置（均为可选；/common-rules 激活时通过命令行参数传入，激活期内仅在会话中持有、跨任务复用；禁止写入任何文件，与规范三联动）：

不发送的情形（静默跳过，不报错、不阻断任务）：

• 任务类型不在上面白名单内（咨询、规划、文档、提交代码、skill 维护等）
• 未配置任何飞书参数（默认状态）
• 配置不全：只传了 --feishu-secret 而缺 --feishu-webhook；或机器人开启加签但未传 --feishu-secret（发送必然 401 时直接跳过并提示"加签参数不全，未发送"）

结果处理：摘要"影响范围"中固定一行 飞书通知：已发送 | 不在发送范围（跳过） | 未配置（跳过） | 发送失败（<一句话原因>）；发送失败最多重试一次，不影响任务完成判定。

消息格式（强制：卡片 JSON 2.0 单栏版式 msg_type: "interactive"）

禁止发送无结构的自由文本段落；禁止用 column_set 分栏排版（实测视觉不佳，本 skill 明确禁用）。卡片固定为 "schema": "2.0" 的单栏结构，全部正文用 markdown 元素承载（不用代码块，以便小标题加粗、条目渲染为有序列表），区块与顺序如下，字段名不得增删改名：

body.elements[1] 为 hr 分隔线（时间行与正文之间）。已知代价：markdown 正文按卡片宽度自动折行（这是选择"加粗标题 + 编号列表"的必然取舍），请把每条摘要条目写成一句话说清，不要在一行里堆多件事。

2.0 相对 1.0 的结构差异（迁移时易错，实测结论）：elements 必须嵌在 body 下（写在顶层报 unknown property: elements）；分隔线标签是 hr（horizontal_line 不支持）；note 元素已废弃（unsupported tag note）；文本元素用 {"tag": "markdown", "content": …}，不再是 div + lark_md；代码块内不渲染任何样式，故正文不入代码块。

内容一致性（强制）：卡片正文必须与规范一摘要逐字一致——保留全部条目、换行、文件路径、编号与标点，禁止精简、压缩、合并同类项、改写措辞、截断或以"等 N 个""详见摘要"替代原文。仅允许三处承载形式差异（文字内容仍须一致）：

1. 标题栏简短化（header.title 长度限制）
2. 小标题符号转换：摘要 ### 任务结果 ↔ 卡片 **任务结果**；摘要的时间行（一行）↔ 卡片三行
3. 卡片内省略摘要的 飞书通知 状态行（发送前不可知）

列表符号两侧统一用 1. 编号（规范一摘要同样用编号，不做 - ↔ 1. 的转换）。

• 单块内容过长时按摘要原顺序拆成多个 markdown 元素（小标题随首块出现一次即可），一字不减
• 整卡超出飞书长度上限导致报错时，按摘要原顺序拆成多条卡片依次发送，每条标题追加 (1/2)、(2/2) 序号
• 唯一保留的内容限制：通知中不得出现 token、密码、含凭证连接串等凭证明文（规范三）

发送方式（参数值仅内联在命令中，禁止落盘写文件；回显给用户时 webhook 只显示到 /hook/ 前）

用 Bash 执行 python3 内联脚本组装 JSON（避免手工转义出错）：

python3 - <<'PY'
import base64, hashlib, hmac, json, time, urllib.request
WEBHOOK, SECRET = "<--feishu-webhook 参数值>", "<--feishu-secret 参数值>"

def md(t):  # 2.0 文本元素（markdown 才渲染 **加粗** 与 1. 有序列表）
    return {"tag": "markdown", "content": t}

# 下列条目 = 规范一摘要各块原文，逐字照搬：保留全部条目、换行、路径、编号与标点，
# 禁止精简压缩、合并同类项、改写措辞或截断。条目符号与摘要一致，统一 1. 2. 3. 编号。
# heredoc 用 'PY' 已关闭 shell 展开，正文含引号、反引号、$ 均安全。
RESULT = """1. 新增 /common-rules 规范九……
2. ……"""
SCOPE = """1. 新增文件：无
2. 修改文件：`.claude/skills/common-rules/SKILL.md`
3. 数据库变更：无"""      # 唯一省略项：摘要中的"飞书通知"状态行（发送前不可知）
TODO = """1. @运维 部署后重启 supervisor 服务 <name>（上线时执行）"""
                            # 无人工介入项时固定为：TODO = "1. 无"

card = {
    "schema": "2.0",
    "config": {"update_multi": True},
    "header": {"title": {"tag": "plain_text", "content": "✅ <任务名>｜<一句话结论>"},
               "template": "orange",            # 无人工待办且全部成功用 green
               "padding": "12px 12px 12px 12px"},
    "body": {"direction": "vertical", "padding": "12px 12px 12px 12px", "elements": [
        md("**开始时间**　YYYY-MM-DD HH:MM:SS\n"
           "**结束时间**　YYYY-MM-DD HH:MM:SS\n"
           "**耗时**　?秒"),
        {"tag": "hr"},
        md(f"**任务结果**\n{RESULT}"),
        md(f"**影响范围**\n{SCOPE}"),
        md(f"**人工待办**\n{TODO}"),
        md("<font color='grey'><工程名> · Qoder common-rules 规范九</font>"),
    ]},
}
payload = {"msg_type": "interactive", "card": card}
if SECRET:  # 机器人开启加签时才有 timestamp + sign
    ts = str(int(time.time()))
    sign = base64.b64encode(hmac.new(SECRET.encode(), f"{ts}\n{SECRET}".encode(),
                                     hashlib.sha256).digest()).decode()
    payload.update(timestamp=ts, sign=sign)
resp = json.loads(urllib.request.urlopen(
    urllib.request.Request(WEBHOOK, json.dumps(payload).encode(),
                           {"Content-Type": "application/json"}), timeout=20).read())
print("code=", resp.get("code", resp.get("StatusCode")),
      "msg=", resp.get("msg") or resp.get("StatusMessage"))  # 必须一起打印 msg
PY

• 未传 --feishu-secret（机器人未开加签）时，去掉 timestamp、sign 两个字段即可
• 成功判定：响应 code（或 StatusCode）为 0

失败诊断（必做）：发送后必须同时读 code 与 msg。卡片是整体校验——任一元素不合法就整卡被拒，外层只返回 code=11246，真正原因在 msg 的 ErrCode / ErrPath / ErrorValue 三元组里，例如：

ErrCode: 200861
ErrPath: ROOT -> body -> elements -> [1](tag: note)
ErrorValue: cards of schema V2 no longer support this capability

只打印 code 会把"用了 2.0 已废弃的 note 元素"误判成"卡片没生效/宽度不合适"，进而做无谓的降级和改版式。排查顺序固定为：读 msg 取 ErrPath → 定位到具体元素 → 对照上面"2.0 相对 1.0 的结构差异"修正 → 重发。ErrPath 末尾的 [N] 就是出错元素在 body.elements 中的下标（实测 note 放在下标 3 时返回 elements -> [3](tag: note)），照它改元素即可，不必整卡重写。

• 回退（禁止跳级）：code != 0 时第一步必须按 ErrPath 修正卡片元素后重发（200861 unsupported tag note、200621 unknown property: elements、not support tag: horizontal_line 等结构类错误都是可修正错误，禁止直接改发行文本）；只有修正后仍失败、或错误明确属卡片能力之外时，才降级为 msg_type: "text" 固定行文本，字段顺序：标题行 → 开始时间/结束时间/耗时（三行）→ **任务结果** → **影响范围** → **人工待办**。两种承载都逐字照搬摘要原文，只换形式不减内容，超限时拆多条并按原顺序标注 (1/2)；除此之外不重复发送，网络超时不重试刷屏
• 卡片与回退文本均失败时：摘要 飞书通知 记 发送失败（<ErrCode> <一句话原因>）（带上 ErrCode，便于复盘），不整段回显响应原文，不影响任务完成判定

十、禁止自造概念，一律使用行业标准术语或通用说法

强制要求：技术文档、代码注释、标识符、数据库列名、接口参数、配置键、状态档位命名，以及回答与方案中的措辞，表达领域里已有既定说法的概念时，一律使用行业标准术语或该领域通用叫法（英文术语用其通行写法，中英语境下可并列给出），禁止自造新名词、新缩写、档位昵称去"重新概括"现成概念。

判定基准——一个说法算"标准"，必须能在下列来源之一查到原词（查不到就按"确需自造"流程走，而不是凭感觉认定它没名字）：

易踩场景对照（中列为应使用的标准说法，右列为自造反例）：

确需自造时，三条同时满足才允许（缺一条就不写）：

1. 已实际检索过上述来源，确认没有对应术语——禁止凭印象说"行业里没这个说法"
2. 概念确属本项目/本设备/本业务私有（私有状态档位、私有 flag 名、新硬件型号名），对外部读者不存在既有期望
3. 首次出现处给出定义 + 与标准说法的对照，并明示"本项目自定义"；命名沿用所在语言的构词法（snake_case / UpperCamelCase、XxxStatus 一类），不起昵称、不用比喻当名字

比喻不得当术语用：口语比喻（"水闸""飘了""双跑""打点""一机两用"）只能作为修辞并加引号，且在首次出现处给出标准技术表述；禁止把比喻升格为被引用、被索引、写进代码标识符与表结构的名词。

方案与分析里的措辞同样适用：不发明"X 支柱""X 层模型""X 三角"这类自造框架去组织结论；要套用现成方法论就点名其出处（如"按 DDD 的限界上下文划分"），不自创一套同名不同实的分层叫法。

发现历史遗留自造词（无论谁写的）：先产出 原用词 → 标准用词（出处） → 出现处数 对照表交用户确认，确认后全库一次性统一（代码标识符、数据库列名与迁移 SQL、接口参数、配置键、文档、前端文案一起改），禁止同义词并存或只改新段落。涉及数据库列名 / 对外接口字段更名时：按规范六同步 dev/test/prod 三套配置，结构变更走 Flyway V*.sql 迁移并保留兼容期，不在应用里直接改名导致新旧环境脱节。

摘要输出要求：术语统一类任务，"任务结果"块必须逐条列出 原用词 → 标准用词（替换处数），"影响范围"注明涉及的文件与章节；是否发送飞书通知仍按规范九白名单判定（改了源码/脚本属代码实现类，纯文档与规范文案改动不发送）。