@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.72ac425 → 0.1.0-dev.7cbbb20

package/miaoda/debug-investigation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debug-investigation
-description: "Debug investigation methodology for the Reviewer agent. LOAD THIS SKILL (via read_file) when caller prompt contains symptom keywords: 卡死 / 白屏 / 修不好 / 修不掉 / 报错 / 定位 bug / 为什么 X 不工作 / 出 bug / 故障 / 已经修了 N 次 / 线上报错 / 线上异常 / 发布后出问题 / 用户反馈线上 / hang / crash / broken / doesn't work / can't figure out / still broken / production error / online issue. For 'user reported symptom, find root cause' tasks. Runs alongside security/performance/correctness review but does not replace them — pattern libraries come from those skills, this skill only owns the investigation flow (Phase 1-3 + 4.5 Architecture Questioning). 触发词：定位 bug, root cause, 症状排查, 线上异常排查"
+description: "Debug investigation methodology for the Reviewer agent. LOAD THIS SKILL (via the Skill tool) when caller prompt contains symptom keywords: 卡死 / 白屏 / 修不好 / 修不掉 / 报错 / 定位 bug / 为什么 X 不工作 / 出 bug / 故障 / 已经修了 N 次 / 线上报错 / 线上异常 / 发布后出问题 / 用户反馈线上 / hang / crash / broken / doesn't work / can't figure out / still broken / production error / online issue. For 'user reported symptom, find root cause' tasks. Runs alongside security/performance/correctness review but does not replace them — pattern libraries come from those skills, this skill only owns the investigation flow (Phase 1-3 + 4.5 Architecture Questioning). 触发词：定位 bug, root cause, 症状排查, 线上异常排查"
 available-agents:
   - Reviewer
 ---
@@ -15,33 +15,42 @@ Reviewer 的工具白名单已物理强制此规则：你无 Edit/Write 权限
 # Phase 1 — Root Cause Investigation (必做)
 
 1. 读 caller prompt 提取症状：What / When / Where / 触发条件，并判定症状
-   发生环境：沙箱预览（dev 态） vs 线上（已发布应用）。caller 出现
-   线上 / 发布后 / 线上用户反馈 / production / online 等表述 → 按线上处理
+   发生环境：沙箱预览（dev 态） vs 线上（已发布应用）。从 caller 转述的用户
+   原话判断：出现 线上 / 发布后 / 线上用户反馈 / production / online 等表述 →
+   按线上处理；用户描述的是应用使用者看到的现象，或判断不了 → 两条链路都查
+   （都是只读）
 2. 日志证据（按环境选链路，两条链路日志互不相通）：
    - **沙箱 dev 态** → ReadLogs browser / server-devserver / client-devserver /
      server，找对应错误栈、请求 / 响应、console error
    - **线上（已发布）** → 见下方「Phase 1 子步骤：线上异常取证」，按当前沙箱
      的线上观测手册拉线上日志。ReadLogs 读不到线上日志——
      不要拿沙箱日志当线上症状的证据
+   - 一条链路查不到事件痕迹（没有对应请求、没有报错）时，不要下「无法考证」的
+     结论：事件多半发生在另一条链路，先查另一条。数据库查询、审计开关只反映
+     当前状态，说明不了是谁、何时改的
 3. 近期改动：`git log --oneline -20 <suspected_file>`，必要时看 `git show <sha>`
 4. 数据流反向追溯（见下方 5 步流程）
 5. 跨组件证据：即使没法 runtime 埋点，也要在报告里列清每层"当前行为 vs
    期望行为"，指出断点
 
-## Phase 1 子步骤：线上异常取证（caller 明确描述线上异常时必做）
+## Phase 1 子步骤：线上异常取证（第 1 步判定需要查线上时必做）
 
-当 caller 明确描述**线上（已发布）环境**的异常表现时，必须拉取线上日志作为
+当第 1 步判定需要查**线上（已发布应用）**时，必须拉取线上日志作为
 证据，禁止只凭静态代码阅读下结论。所有取证在 Phase 1 内完成（Reviewer 的
 Phase 3 禁止工具调用规则不变）。
 
-1. **加载命令手册**：Glob 定位当前沙箱的线上观测手册，依次试
-   `**/lark-apps-ops/references/lark-apps-observability.md` 和
-   `**/miaoda-cli/references/observability.md`，命中哪份就用 Read 加载哪份。
+1. **加载命令手册**：在 Available Skills 里找 `lark-apps-ops` 或 `miaoda-cli`，
+   按其 location 推出同目录下的 `references/lark-apps-observability.md` /
+   `references/observability.md`，用 Read 加载存在的那份（不要用 Glob / rg
+   在文件系统里搜：`.agent/` 被应用 .gitignore 忽略，会搜不到）。
    完整命令 / flag / 默认值一律以该文档为准，不要凭记忆拼命令。
    两份都找不到 → 当前栈不支持线上日志查询，在报告里注明
    「线上日志不可用」，回退沙箱日志 + 静态分析，不阻塞调查
 2. **错误日志**：按手册的日志检索条目拉 ERROR 级日志，时间窗按 caller 描述
    的发生时间收敛（如最近 1 小时）；有关键词或具体接口时，按手册支持的方式收窄
+   **请求追溯**：要找某个数据 / 资源被哪个请求改动时，不限 ERROR 级，按资源
+   id、标题、关键词或接口路径加时间窗检索；日志条目带时间戳、method、path、
+   user_id、trace_id，可直接回答「哪个请求、谁、何时」
 3. **链路追溯**：从日志取 `trace_id`，按手册的 trace 检索条目看完整调用链，
    定位慢点 / 失败环节
 4. **前端报错反解源码**：日志含前端错误时，按手册的前端源码反解条目拿到

package/miaoda/forms-skill/SKILL.md

@@ -13,6 +13,11 @@ Shadcn Form + React Hook Form + Zod 表单开发。
 - 所有字段必须有默认值
 - 必须用 Shadcn 组件，禁止原生 input
 - 同行 FormField 必须等宽
+- 每个控件都要有能读出来的字段名（读屏和自动化验收都按它找控件）：FormField 内用 `FormLabel` + `FormControl`，id 会自动关联；FormField 外的筛选、搜索控件用 `<Label htmlFor="x">` 配控件 `id="x"`，没有可见标签时加 `aria-label`。不要只靠 placeholder 或当前选中值表达字段含义
+- 必填星号加 `aria-hidden="true"`，别让 `*` 混进字段名
+- 字段校验错误用 `<FormMessage />` 显示在字段下方；toast 只用于提交结果（成功 / 接口失败），不要用 toast 提示「请输入 xx」
+- 日期字段用 `Popover` + `Calendar`，`FormControl` 包住触发按钮，禁止 `input[type="date"]`
+- 自定义输入组件（富文本等）也放进 `FormControl`，并把 `id`、`aria-*` 透传到真正可编辑的元素上
 - 表单提交到必填 API/DTO/Request/interface 前，先读目标 shared/server 类型，在 `handleSubmit` 回调里用 `data` 逐字段构造 typed request（见 Patterns）；不要整体传 `data`、`schema.parse(data)` 或 `.required().parse(data)`，也不要用 `any`/`as` 绕过 TS2322。修完后跑 LSP 或 `typecheck`。
 
 ---
@@ -49,14 +54,14 @@ export function StudentForm() {
         <div className="flex flex-wrap gap-4">
           <FormField control={form.control} name="name" render={({ field }) => (
             <FormItem className="flex-1">
-              <FormLabel>姓名 <span className="text-destructive">*</span></FormLabel>
+              <FormLabel>姓名 <span aria-hidden="true" className="text-destructive">*</span></FormLabel>
               <FormControl><Input placeholder="请输入姓名" {...field} /></FormControl>
               <FormMessage />
             </FormItem>
           )} />
           <FormField control={form.control} name="age" render={({ field }) => (
             <FormItem className="flex-1">
-              <FormLabel>年龄 <span className="text-destructive">*</span></FormLabel>
+              <FormLabel>年龄 <span aria-hidden="true" className="text-destructive">*</span></FormLabel>
               <FormControl><Input type="number" {...field} /></FormControl>
               <FormMessage />
             </FormItem>
@@ -64,7 +69,7 @@ export function StudentForm() {
         </div>
         <FormField control={form.control} name="grade" render={({ field }) => (
           <FormItem>
-            <FormLabel>年级 <span className="text-destructive">*</span></FormLabel>
+            <FormLabel>年级 <span aria-hidden="true" className="text-destructive">*</span></FormLabel>
             <Select onValueChange={field.onChange} defaultValue={field.value}>
               <FormControl><SelectTrigger><SelectValue placeholder="请选择" /></SelectTrigger></FormControl>
               <SelectContent>
@@ -99,7 +104,35 @@ const form = useForm<FormData>({ resolver: zodResolver(schema), defaultValues: {
 </div>
 
 // 必填标记
-<FormLabel>字段 <span className="text-destructive">*</span></FormLabel>
+<FormLabel>字段 <span aria-hidden="true" className="text-destructive">*</span></FormLabel>
+
+// 表单外的筛选 / 搜索控件：可见标签用 htmlFor + id 关联；没有可见标签必须加 aria-label
+<Label htmlFor="status-filter">状态</Label>
+<Select value={status} onValueChange={setStatus}>
+  <SelectTrigger id="status-filter"><SelectValue placeholder="全部状态" /></SelectTrigger>
+  <SelectContent>{/* SelectItem ... */}</SelectContent>
+</Select>
+<Input aria-label="搜索姓名或职位" placeholder="搜索姓名或职位" value={keyword} onChange={(e) => setKeyword(e.target.value)} />
+
+// 日期：Popover + Calendar，FormControl 包住触发按钮，label 才能关联到它
+<FormField control={form.control} name="dueDate" render={({ field }) => (
+  <FormItem>
+    <FormLabel>截止日期</FormLabel>
+    <Popover>
+      <PopoverTrigger asChild>
+        <FormControl>
+          <Button variant="outline" className="w-full justify-start font-normal">
+            {field.value ? dayjs(field.value).format("YYYY-MM-DD") : "请选择日期"}
+          </Button>
+        </FormControl>
+      </PopoverTrigger>
+      <PopoverContent className="w-auto p-0" align="start">
+        <Calendar mode="single" selected={field.value} onSelect={field.onChange} />
+      </PopoverContent>
+    </Popover>
+    <FormMessage />
+  </FormItem>
+)} />
 
 // 必填 Request/DTO 桥接：zodResolver 负责运行时校验，DTO 边界负责静态类型匹配。
 // 用 handleSubmit 回调的 data，不要用 getValues（拿到的是 coerce 前的原始值）。

package/miaoda/lark-apps-db/SKILL.md

@@ -133,6 +133,7 @@ CREATE POLICY "修改本人数据" ON <table>
 5. 执行前向用户展示目标对象和变更内容；DROP / DROP COLUMN 还要说明数据丢失风险并取得明确授权。
 6. 执行：`lark-cli apps +db-execute --app-id "$app_id" --sql "<ddl>" --yes`。多条 DDL 是一个逻辑单元时放在一次调用；需要全回滚则显式包事务。
 7. DDL 成功后**立即**在应用工程根目录执行 `npm run gen:db-schema` 刷新 `server/database/schema.ts`——`+db-execute` 不会自动刷新。多批 DDL 每批成功后都跑一次。
+8. 已存在的表只能用 `ALTER TABLE` 修改。`CREATE TABLE IF NOT EXISTS` 只会跳过建表，**不会**更新已有列的类型、默认值或约束；执行 `ALTER TABLE` 后再次用 `+db-table-get --table <table>` 回读 DDL，确认目标定义已经改变。
 
 ### DDL Do / Don't
 
@@ -160,6 +161,11 @@ CREATE POLICY "修改本人数据" ON <table>
 | 标量子查询多行 | `VALUES((SELECT ...))` / `SET col=(SELECT ...)` 必须唯一或 `ORDER BY ... LIMIT 1` |
 | 系统表查询 | 常规结构查询用 `+db-table-list/get`；系统表仅限 reference 中列出的白名单 |
 | 多语句事务误判 | `A; B; C` 不自动包事务，B 失败时 A 不回滚；需要原子性用 `BEGIN/COMMIT` |
+| 时间表达式依赖会话时区 | `timestamptz` 参与日期/小时计算、CHECK 或表达式索引时，显式写 `AT TIME ZONE 'UTC'` 或明确的业务时区；用跨日期边界的时间值验证结果，禁止依赖会话默认时区 |
+
+### 写入前核对全部唯一性
+
+新增或修改 `INSERT`、`UPDATE`、upsert 写入逻辑前，先用 `+db-table-get --table <table> --format pretty` 读取目标表完整 DDL，列出其中**全部** UNIQUE 约束和唯一索引（含条件索引、表达式索引），逐条检查本次写入是否可能冲突。`ON CONFLICT` 只处理它明确匹配的那一条唯一规则，不能挡住其它唯一索引；发现其它冲突时，应在写入前按业务语义处理，或将 `23505` 转成明确的冲突错误，禁止让它冒成 500。
 
 ## Data Types and Design
 

package/miaoda/miaoda-sql/SKILL.md

@@ -121,6 +121,7 @@ CREATE POLICY "修改本人数据" ON <table>
 4. CREATE TABLE / CREATE INDEX / ALTER TABLE ADD COLUMN 必须带 `IF NOT EXISTS`，避免重复执行失败。
 5. 执行前向用户展示目标对象和变更内容；DROP / DROP COLUMN 还要说明数据丢失风险并取得明确授权。
 6. 执行：`miaoda db sql "<ddl>"`。多条 DDL 是一个逻辑单元时放在一次调用；需要全回滚则显式包事务。
+7. 已存在的表只能用 `ALTER TABLE` 修改。`CREATE TABLE IF NOT EXISTS` 只会跳过建表，**不会**更新已有列的类型、默认值或约束；执行 `ALTER TABLE` 后再次用 `miaoda db schema get <table>` 回读 DDL，确认目标定义已经改变。
 
 ### DDL Do / Don't
 
@@ -149,6 +150,11 @@ CREATE POLICY "修改本人数据" ON <table>
 | 标量子查询多行 | `VALUES((SELECT ...))` / `SET col=(SELECT ...)` 必须唯一或 `ORDER BY ... LIMIT 1` |
 | 系统表查询 | 常规结构查询用 schema 命令；系统表仅限 reference 中列出的白名单 |
 | 多语句事务误判 | `A; B; C` 不自动包事务，B 失败时 A 不回滚；需要原子性用 `BEGIN/COMMIT` |
+| 时间表达式依赖会话时区 | `timestamptz` 参与日期/小时计算、CHECK 或表达式索引时，显式写 `AT TIME ZONE 'UTC'` 或明确的业务时区；用跨日期边界的时间值验证结果，禁止依赖会话默认时区 |
+
+### 写入前核对全部唯一性
+
+新增或修改 `INSERT`、`UPDATE`、upsert 写入逻辑前，先用 `miaoda db schema get <table>` 读取目标表完整 DDL，列出其中**全部** UNIQUE 约束和唯一索引（含条件索引、表达式索引），逐条检查本次写入是否可能冲突。`ON CONFLICT` 只处理它明确匹配的那一条唯一规则，不能挡住其它唯一索引；发现其它冲突时，应在写入前按业务语义处理，或将 `23505` 转成明确的冲突错误，禁止让它冒成 500。
 
 ## Data Types and Design
 

package/miaoda-modern/debug-investigation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debug-investigation
-description: "Debug investigation methodology for the Reviewer agent. LOAD THIS SKILL (via read_file) when caller prompt contains symptom keywords: 卡死 / 白屏 / 修不好 / 修不掉 / 报错 / 定位 bug / 为什么 X 不工作 / 出 bug / 故障 / 已经修了 N 次 / hang / crash / broken / doesn't work / can't figure out / still broken. For 'user reported symptom, find root cause' tasks. Runs alongside security/performance/correctness review but does not replace them — pattern libraries come from those skills, this skill only owns the investigation flow (Phase 1-3 + 4.5 Architecture Questioning). 触发词：定位 bug, root cause, 症状排查"
+description: "Debug investigation methodology for the Reviewer agent. LOAD THIS SKILL (via the Skill tool) when caller prompt contains symptom keywords: 卡死 / 白屏 / 修不好 / 修不掉 / 报错 / 定位 bug / 为什么 X 不工作 / 出 bug / 故障 / 已经修了 N 次 / hang / crash / broken / doesn't work / can't figure out / still broken. For 'user reported symptom, find root cause' tasks. Runs alongside security/performance/correctness review but does not replace them — pattern libraries come from those skills, this skill only owns the investigation flow (Phase 1-3 + 4.5 Architecture Questioning). 触发词：定位 bug, root cause, 症状排查"
 available-agents:
   - Reviewer
 ---

package/miaoda-modern/forms-skill/SKILL.md

@@ -15,6 +15,11 @@ Shadcn Form + React Hook Form + Zod 表单开发。
 - API 合同允许字段可选的查询、筛选、搜索表单，继续提交 `z.infer` 值
 - 必须用 Shadcn 组件，禁止原生 input
 - 同行 FormField 必须等宽
+- 每个控件都要有能读出来的字段名（读屏和自动化验收都按它找控件）：FormField 内用 `FormLabel` + `FormControl`，id 会自动关联；FormField 外的筛选、搜索控件用 `<Label htmlFor="x">` 配控件 `id="x"`，没有可见标签时加 `aria-label`。不要只靠 placeholder 或当前选中值表达字段含义
+- 必填星号加 `aria-hidden="true"`，别让 `*` 混进字段名
+- 字段校验错误用 `<FormMessage />` 显示在字段下方；toast 只用于提交结果（成功 / 接口失败），不要用 toast 提示「请输入 xx」
+- 日期字段用 `Popover` + `Calendar`，`FormControl` 包住触发按钮，禁止 `input[type="date"]`
+- 自定义输入组件（富文本等）也放进 `FormControl`，并把 `id`、`aria-*` 透传到真正可编辑的元素上
 - 表单提交到必填 API/DTO/Request/interface 前，先读目标 shared/server 类型，在 `handleSubmit` 回调里用 `data` 逐字段构造 typed request（见 Patterns）；不要整体传 `data`、`schema.parse(data)` 或 `.required().parse(data)`，也不要用 `any`/`as` 绕过 TS2322。修完后跑 LSP 或 `typecheck`。
 
 ---
@@ -70,14 +75,14 @@ export function StudentForm() {
         <div className="flex flex-wrap gap-4">
           <FormField control={form.control} name="name" render={({ field }) => (
             <FormItem className="flex-1">
-              <FormLabel>姓名 <span className="text-destructive">*</span></FormLabel>
+              <FormLabel>姓名 <span aria-hidden="true" className="text-destructive">*</span></FormLabel>
               <FormControl><Input placeholder="请输入姓名" {...field} /></FormControl>
               <FormMessage />
             </FormItem>
           )} />
           <FormField control={form.control} name="age" render={({ field }) => (
             <FormItem className="flex-1">
-              <FormLabel>年龄 <span className="text-destructive">*</span></FormLabel>
+              <FormLabel>年龄 <span aria-hidden="true" className="text-destructive">*</span></FormLabel>
               <FormControl><Input type="number" {...field} /></FormControl>
               <FormMessage />
             </FormItem>
@@ -85,7 +90,7 @@ export function StudentForm() {
         </div>
         <FormField control={form.control} name="grade" render={({ field }) => (
           <FormItem>
-            <FormLabel>年级 <span className="text-destructive">*</span></FormLabel>
+            <FormLabel>年级 <span aria-hidden="true" className="text-destructive">*</span></FormLabel>
             <Select onValueChange={field.onChange} defaultValue={field.value}>
               <FormControl><SelectTrigger><SelectValue placeholder="请选择" /></SelectTrigger></FormControl>
               <SelectContent>
@@ -120,7 +125,35 @@ const form = useForm<FormData>({ resolver: zodResolver(schema), defaultValues: {
 </div>
 
 // 必填标记
-<FormLabel>字段 <span className="text-destructive">*</span></FormLabel>
+<FormLabel>字段 <span aria-hidden="true" className="text-destructive">*</span></FormLabel>
+
+// 表单外的筛选 / 搜索控件：可见标签用 htmlFor + id 关联；没有可见标签必须加 aria-label
+<Label htmlFor="status-filter">状态</Label>
+<Select value={status} onValueChange={setStatus}>
+  <SelectTrigger id="status-filter"><SelectValue placeholder="全部状态" /></SelectTrigger>
+  <SelectContent>{/* SelectItem ... */}</SelectContent>
+</Select>
+<Input aria-label="搜索姓名或职位" placeholder="搜索姓名或职位" value={keyword} onChange={(e) => setKeyword(e.target.value)} />
+
+// 日期：Popover + Calendar，FormControl 包住触发按钮，label 才能关联到它
+<FormField control={form.control} name="dueDate" render={({ field }) => (
+  <FormItem>
+    <FormLabel>截止日期</FormLabel>
+    <Popover>
+      <PopoverTrigger asChild>
+        <FormControl>
+          <Button variant="outline" className="w-full justify-start font-normal">
+            {field.value ? dayjs(field.value).format("YYYY-MM-DD") : "请选择日期"}
+          </Button>
+        </FormControl>
+      </PopoverTrigger>
+      <PopoverContent className="w-auto p-0" align="start">
+        <Calendar mode="single" selected={field.value} onSelect={field.onChange} />
+      </PopoverContent>
+    </Popover>
+    <FormMessage />
+  </FormItem>
+)} />
 
 // 必填 Request/DTO 桥接：zodResolver 负责运行时校验，DTO 边界负责静态类型匹配。
 // 用 handleSubmit 回调的 data，不要用 getValues（拿到的是 coerce 前的原始值）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-miaoda-sandbox-skills",
-  "version": "0.1.0-dev.72ac425",
+  "version": "0.1.0-dev.7cbbb20",
   "description": "Miaoda 合并沙箱 skills 包（包含原 miaoda-skills 的 miaoda / miaoda-modern / miaoda-design / shared 四条业务线）；发布公网 npm，随沙箱运行时经 update-skills 同步到 .agent/skills/",
   "type": "module",
   "files": [