@bovinphang/craft-common 1.0.0 → 2.0.0

package/localized/zh-CN/skills/cc-typescript-project-standard/references/type-safety.md

@@ -0,0 +1,154 @@
+# TypeScript 类型安全
+
+## 用途
+
+为前端和 TypeScript 工程建立可演进的类型契约，减少 `any`、断言和运行时形状漂移。
+
+## 流程
+
+### 1. 先确定类型边界
+
+把类型分为外部输入、领域模型、UI view model、组件 props、工具函数 API。不要让后端 DTO、表单模型和 UI 展示模型互相冒充。
+
+```ts
+interface UserDto {
+  id: string;
+  display_name: string;
+  status: "ACTIVE" | "DISABLED";
+}
+
+interface UserViewModel {
+  id: string;
+  displayName: string;
+  status: "active" | "disabled";
+}
+
+export function mapUserDto(dto: UserDto): UserViewModel {
+  return {
+    id: dto.id,
+    displayName: dto.display_name,
+    status: dto.status === "ACTIVE" ? "active" : "disabled",
+  };
+}
+```
+
+### 2. 用 `unknown` 和收窄处理不可信数据
+
+外部输入先校验再使用。不要用 `as` 让编译器闭嘴。
+
+```ts
+interface ApiErrorBody {
+  message: string;
+}
+
+function isApiErrorBody(value: unknown): value is ApiErrorBody {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "message" in value &&
+    typeof value.message === "string"
+  );
+}
+
+export function getApiErrorMessage(value: unknown): string {
+  return isApiErrorBody(value) ? value.message : "Unexpected error";
+}
+```
+
+### 3. 用判别联合表达状态机
+
+异步状态、权限分支、支付状态等有限状态，用判别字段让新增分支在编译期暴露。
+
+```ts
+type Loadable<T> =
+  | { state: "idle" }
+  | { state: "loading" }
+  | { state: "success"; data: T }
+  | { state: "error"; error: Error };
+
+function assertNever(value: never): never {
+  throw new Error(`Unhandled state: ${JSON.stringify(value)}`);
+}
+
+export function renderUserState(user: Loadable<{ name: string }>): string {
+  switch (user.state) {
+    case "idle":
+      return "Ready";
+    case "loading":
+      return "Loading";
+    case "success":
+      return user.data.name;
+    case "error":
+      return user.error.message;
+    default:
+      return assertNever(user);
+  }
+}
+```
+
+### 4. 让泛型服务调用方，而不是炫技
+
+泛型应减少重复并保持调用方推断清晰。复杂类型超过阅读成本时，优先拆具名类型。
+
+```ts
+interface SelectOption<TValue extends string | number> {
+  label: string;
+  value: TValue;
+}
+
+interface SelectProps<TValue extends string | number> {
+  value: TValue;
+  options: Array<SelectOption<TValue>>;
+  onChange: (value: TValue) => void;
+}
+
+export function Select<TValue extends string | number>({
+  value,
+  options,
+  onChange,
+}: SelectProps<TValue>) {
+  return (
+    <select value={value} onChange={(event) => onChange(event.target.value as TValue)}>
+      {options.map((option) => (
+        <option key={option.value} value={option.value}>
+          {option.label}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+### 5. 用类型测试保护公共类型
+
+公共工具类型、组件库类型和 SDK 类型，应有轻量类型测试或编译期断言。
+
+```ts
+type Equal<TLeft, TRight> =
+  (<T>() => T extends TLeft ? 1 : 2) extends <T>() => T extends TRight ? 1 : 2
+    ? true
+    : false;
+
+type Expect<T extends true> = T;
+
+type UserStatus = UserViewModel["status"];
+type _UserStatusTest = Expect<Equal<UserStatus, "active" | "disabled">>;
+```
+
+## 约束
+
+- 避免 `any`、无守卫的非空断言和不相关类型之间的强制 `as`。
+- 不把大型匿名类型堆在函数参数或 JSX props 上；提取具名类型表达业务含义。
+- 不为简单业务过度设计递归条件类型；类型复杂度应服务可维护性。
+- 公共 API 的输入输出必须显式标注，局部变量可依赖推断。
+- 类型建模不能替代运行时校验；外部数据仍需 schema 或 type guard。
+
+## 预期输出
+
+产出清晰的类型边界、可收窄的数据模型、必要的类型测试和验证命令。评审时应列出类型风险、运行时影响、推荐建模方式和是否需要专项修复。
+
+## 与应用工作流的边界
+
+- 涉及组件架构、路由、状态归属和框架专项模块边界时，使用框架项目工作流。
+- 当runtime API clients, auth refresh, uploads, realtime behavior, or error mapping go beyond TypeScript type contracts时，使用 API 集成。
+- 当the task is to repair concrete lint, typecheck, test, build, or CI failures after TypeScript changes时，使用验证修复 fix。

package/localized/zh-CN/skills/eval_queries.json

@@ -1,4 +1,52 @@
 {
+  "cc-c-project-standard": {
+    "should_trigger": [
+      "审查或修复C 分配失败清理路径",
+      "审查或修复C 库 ABI 兼容性",
+      "审查或修复C 失败输出初始化",
+      "审查或修复C 缓冲区长度校验",
+      "审查或修复C 分配时整数溢出",
+      "审查或修复纯 C 所有权转移",
+      "审查或修复C 头文件与实现边界",
+      "审查或修复C 失败注入测试",
+      "评审纯C分配大小及分配器配对，不迁移C++"
+    ],
+    "should_not_trigger": [
+      "只调整 CSS 间距，不改程序契约",
+      "翻译产品文案，不涉及程序",
+      "生成海报插图",
+      "推荐晚餐餐厅",
+      "只修改数据库索引，没有语言代码",
+      "只设计框架组件路由，不改语言配置",
+      "重写营销标题",
+      "生成音频配乐",
+      "只翻译包含该技术名称的说明文字，不修改或评审任何程序"
+    ]
+  },
+  "cc-cpp-project-standard": {
+    "should_trigger": [
+      "审查或修复C++ 库 RAII 所有权",
+      "审查或修复C++ 异常保证",
+      "审查或修复C++ 桌面插件 ABI",
+      "审查或修复C++ 部分构造清理",
+      "审查或修复C++ 回调生命周期",
+      "审查或修复保持 C++ 编译标准",
+      "审查或修复C++ 自定义 deleter 配对",
+      "审查或修复C++ 模块退出同步",
+      "评审C++插件借用指针清理，保留禁异常政策"
+    ],
+    "should_not_trigger": [
+      "只调整 CSS 间距，不改程序契约",
+      "翻译产品文案，不涉及程序",
+      "生成海报插图",
+      "推荐晚餐餐厅",
+      "只修改数据库索引，没有语言代码",
+      "只设计框架组件路由，不改语言配置",
+      "重写营销标题",
+      "生成音频配乐",
+      "只翻译包含该技术名称的说明文字，不修改或评审任何程序"
+    ]
+  },
   "cc-debug-methodology": {
     "should_trigger": [
       "Vite 构建报错 Module not found，帮我排查",
@@ -69,6 +117,198 @@
       "生成漫画头像和品牌板"
     ]
   },
+  "cc-electron-project-standard": {
+    "should_trigger": [
+      "在副作用前校验 Electron IPC sender",
+      "限制 contextBridge 的逐项接口",
+      "审查 main/preload/renderer 契约",
+      "核验 Electron sandbox 边界",
+      "限制导航和新窗口",
+      "审查安全自定义协议资源",
+      "检查原生模块 ABI 与打包",
+      "管理退出时 IPC handler 生命周期",
+      "评审Electron窗口关闭后IPC准备迟到的副作用"
+    ],
+    "should_not_trigger": [
+      "实现没有 Electron 的 Node HTTP API",
+      "整理普通 Rust 库",
+      "只改 Vue CSS 颜色",
+      "设计 Tauri capabilities",
+      "调整 Go worker channel",
+      "翻译营销标题",
+      "审查数据库隔离级别",
+      "生成图表而不改程序",
+      "只翻译包含该技术名称的说明文字，不修改或评审任何程序"
+    ]
+  },
+  "cc-go-concurrency": {
+    "should_trigger": [
+      "审查或修复Go worker 取消",
+      "审查或修复Go channel 关闭归属",
+      "审查或修复接收方退出后 Go 发送阻塞",
+      "审查或修复Go goroutine 数量上限",
+      "审查或修复Go 同步先行关系",
+      "审查或修复Go 并发退出竞态",
+      "审查或修复Go 队列饱和测试",
+      "审查或修复Go worker 退出完成证据",
+      "评审Go通道阻塞关闭及两个工作者完成"
+    ],
+    "should_not_trigger": [
+      "只调整 CSS 间距，不改程序契约",
+      "翻译产品文案，不涉及程序",
+      "生成海报插图",
+      "推荐晚餐餐厅",
+      "只修改数据库索引，没有语言代码",
+      "只设计框架组件路由，不改语言配置",
+      "重写营销标题",
+      "生成音频配乐",
+      "只翻译包含该技术名称的说明文字，不修改或评审任何程序"
+    ]
+  },
+  "cc-go-project-standard": {
+    "should_trigger": [
+      "审查或修复go.work 子模块边界",
+      "审查或修复Go internal 包组织",
+      "审查或修复Go CLI 错误包装",
+      "审查或修复阻塞操作的 context 所有者",
+      "审查或修复Go 资源工厂清理",
+      "审查或修复Go 模块导入兼容性",
+      "审查或修复当前模块的 vet 与 test 命令",
+      "审查或修复Go 公共接口设计",
+      "评审Go库context和错误边界，不添加HTTP分层"
+    ],
+    "should_not_trigger": [
+      "只调整 CSS 间距，不改程序契约",
+      "翻译产品文案，不涉及程序",
+      "生成海报插图",
+      "推荐晚餐餐厅",
+      "只修改数据库索引，没有语言代码",
+      "只设计框架组件路由，不改语言配置",
+      "重写营销标题",
+      "生成音频配乐",
+      "只翻译包含该技术名称的说明文字，不修改或评审任何程序"
+    ]
+  },
+  "cc-java-project-standard": {
+    "should_trigger": [
+      "审查或修复Java 库的公共模块边界",
+      "审查或修复Java CLI 异常原因",
+      "审查或修复Swing 模块线程池关闭",
+      "审查或修复JavaFX 阻塞工作归属",
+      "审查或修复Maven wrapper 版本保持",
+      "审查或修复Gradle 模块依赖边界",
+      "审查或修复Java 文件句柄关闭",
+      "审查或修复Java 库行为测试",
+      "评审Java库部分初始化及cause，不加入Web框架"
+    ],
+    "should_not_trigger": [
+      "只调整 CSS 间距，不改程序契约",
+      "翻译产品文案，不涉及程序",
+      "生成海报插图",
+      "推荐晚餐餐厅",
+      "只修改数据库索引，没有语言代码",
+      "只设计框架组件路由，不改语言配置",
+      "重写营销标题",
+      "生成音频配乐",
+      "只翻译包含该技术名称的说明文字，不修改或评审任何程序"
+    ]
+  },
+  "cc-java-runtime": {
+    "should_trigger": [
+      "审查或修复JVM 线程池队列增长",
+      "审查或修复Java 桌面线程竞争",
+      "审查或修复有界 JFR 取证",
+      "审查或修复Java GC 分配压力",
+      "审查或修复Java 操作期限与过载",
+      "审查或修复Java 堆配置受控对照",
+      "审查或修复Java 重复线程栈采样",
+      "审查或修复Java 运行时恢复阈值",
+      "诊断所属Java执行器请求关闭后不退出"
+    ],
+    "should_not_trigger": [
+      "只调整 CSS 间距，不改程序契约",
+      "翻译产品文案，不涉及程序",
+      "生成海报插图",
+      "推荐晚餐餐厅",
+      "只修改数据库索引，没有语言代码",
+      "只设计框架组件路由，不改语言配置",
+      "重写营销标题",
+      "生成音频配乐",
+      "只翻译包含该技术名称的说明文字，不修改或评审任何程序"
+    ]
+  },
+  "cc-native-memory-safety": {
+    "should_trigger": [
+      "审查或修复C/C++ FFI 分配释放配对",
+      "审查或修复Rust 原生借用缓冲区生命周期",
+      "审查或修复卸载后的原生回调",
+      "审查或修复C 部分初始化失败",
+      "审查或修复C++ 跨 DLL 异常边界",
+      "审查或修复原生重复关闭行为",
+      "审查或修复原生并发析构竞态",
+      "审查或修复地址检查工具的复现证据",
+      "评审原生插件分配器释放及卸载前回调完成"
+    ],
+    "should_not_trigger": [
+      "只调整 CSS 间距，不改程序契约",
+      "翻译产品文案，不涉及程序",
+      "生成海报插图",
+      "推荐晚餐餐厅",
+      "只修改数据库索引，没有语言代码",
+      "只设计框架组件路由，不改语言配置",
+      "重写营销标题",
+      "生成音频配乐",
+      "只翻译包含该技术名称的说明文字，不修改或评审任何程序"
+    ]
+  },
+  "cc-python-async": {
+    "should_trigger": [
+      "审查或修复Python task 取消清理",
+      "审查或修复Python 阻塞 client 转移",
+      "审查或修复Python 异步 executor 上限",
+      "审查或修复Python 异步池归属",
+      "审查或修复Python TaskGroup 错误传播",
+      "审查或修复Python 协程退出期限",
+      "审查或修复取消后的 Python 线程生命周期",
+      "审查或修复Python 异步资源获取超时",
+      "评审asyncio等待方取消后底层阻塞操作仍运行"
+    ],
+    "should_not_trigger": [
+      "只调整 CSS 间距，不改程序契约",
+      "翻译产品文案，不涉及程序",
+      "生成海报插图",
+      "推荐晚餐餐厅",
+      "只修改数据库索引，没有语言代码",
+      "只设计框架组件路由，不改语言配置",
+      "重写营销标题",
+      "生成音频配乐",
+      "只翻译包含该技术名称的说明文字，不修改或评审任何程序"
+    ]
+  },
+  "cc-python-project-standard": {
+    "should_trigger": [
+      "审查或修复Python CLI 包布局",
+      "审查或修复pyproject 环境约定",
+      "审查或修复Python 库类型边界",
+      "审查或修复Python 导入时副作用",
+      "审查或修复Python 资源上下文管理器",
+      "审查或修复既有 Ruff、mypy、pytest 命令",
+      "审查或修复Python 公共包导入",
+      "审查或修复Python 非法输入行为",
+      "消除Python库导入时外部初始化并保留清理"
+    ],
+    "should_not_trigger": [
+      "只调整 CSS 间距，不改程序契约",
+      "翻译产品文案，不涉及程序",
+      "生成海报插图",
+      "推荐晚餐餐厅",
+      "只修改数据库索引，没有语言代码",
+      "只设计框架组件路由，不改语言配置",
+      "重写营销标题",
+      "生成音频配乐",
+      "只翻译包含该技术名称的说明文字，不修改或评审任何程序"
+    ]
+  },
   "cc-refactoring-core": {
     "should_trigger": [
       "保持行为不变，重构这个前端模块。",
@@ -91,6 +331,54 @@
       "按 Figma 新增一个响应式页面。"
     ]
   },
+  "cc-rust-async": {
+    "should_trigger": [
+      "审查或修复Rust future 取消安全",
+      "审查或修复Tokio 部分写入取消",
+      "审查或修复Rust spawn 任务数量上限",
+      "审查或修复Rust JoinHandle 退出归属",
+      "审查或修复Rust 阻塞 I/O 边界",
+      "审查或修复Rust 异步队列背压",
+      "审查或修复Rust 资源获取期间的取消",
+      "审查或修复Rust 异步超时恢复",
+      "评审桌面窗口关闭后既有Rust异步任务取消及等待"
+    ],
+    "should_not_trigger": [
+      "只调整 CSS 间距，不改程序契约",
+      "翻译产品文案，不涉及程序",
+      "生成海报插图",
+      "推荐晚餐餐厅",
+      "只修改数据库索引，没有语言代码",
+      "只设计框架组件路由，不改语言配置",
+      "重写营销标题",
+      "生成音频配乐",
+      "只翻译包含该技术名称的说明文字，不修改或评审任何程序"
+    ]
+  },
+  "cc-rust-project-standard": {
+    "should_trigger": [
+      "审查或修复Cargo workspace 的 crate 边界",
+      "审查或修复Rust MSRV 与 edition 配置",
+      "审查或修复Rust 库借用契约",
+      "审查或修复Rust CLI 的 Result 传播",
+      "审查或修复Rust 公共模块可见性",
+      "审查或修复Rust 库发布检查",
+      "审查或修复Rust 适配器依赖方向",
+      "审查或修复Rust 资源所有权转移",
+      "评审桌面核心Rust Result原因及部分获取清理"
+    ],
+    "should_not_trigger": [
+      "只调整 CSS 间距，不改程序契约",
+      "翻译产品文案，不涉及程序",
+      "生成海报插图",
+      "推荐晚餐餐厅",
+      "只修改数据库索引，没有语言代码",
+      "只设计框架组件路由，不改语言配置",
+      "重写营销标题",
+      "生成音频配乐",
+      "只翻译包含该技术名称的说明文字，不修改或评审任何程序"
+    ]
+  },
   "cc-source-driven-development": {
     "should_trigger": [
       "这个 Next.js 新版本 API 先查官方文档再决定",
@@ -113,6 +401,30 @@
       "审查 token 存储安全"
     ]
   },
+  "cc-tauri-project-standard": {
+    "should_trigger": [
+      "审查 Tauri command 输入校验",
+      "将 Tauri 2 capability 限制到指定窗口",
+      "检查应用 command 的权限生成",
+      "设计 invoke 错误契约",
+      "管理 Tauri 托管状态退出",
+      "限制 Tauri 核心阻塞工作",
+      "验证目标平台资源打包",
+      "审查插件和 sidecar 权限",
+      "评审Tauri2实际选中capability与应用命令权限边界"
+    ],
+    "should_not_trigger": [
+      "整理没有 Tauri 的普通 Rust 库",
+      "优化没有 WebView 的 Node HTTP 服务",
+      "只改 React CSS 间距",
+      "设计 Go CLI 参数",
+      "修改 Electron preload",
+      "翻译海报文案",
+      "审查 SQL 执行计划",
+      "格式化无关 Python 文件",
+      "只翻译包含该技术名称的说明文字，不修改或评审任何程序"
+    ]
+  },
   "cc-tdd-methodology": {
     "should_trigger": [
       "用 TDD 实现这个 hook",
@@ -156,5 +468,29 @@
       "编写 CLI 单元测试",
       "润色营销文案"
     ]
+  },
+  "cc-typescript-project-standard": {
+    "should_trigger": [
+      "审查或修复TypeScript SDK 声明导出",
+      "审查或修复TypeScript CLI 的 NodeNext 解析",
+      "审查或修复TypeScript 桌面 preload 契约",
+      "审查或修复TypeScript unknown 输入收窄",
+      "审查或修复TypeScript 判别联合 API",
+      "审查或修复TypeScript monorepo 项目引用",
+      "审查或修复TypeScript 泛型库约束",
+      "审查或修复TypeScript 消费方类型测试",
+      "评审TypeScript库unknown输入副作用边界，保持模块模式"
+    ],
+    "should_not_trigger": [
+      "只调整 CSS 间距，不改程序契约",
+      "翻译产品文案，不涉及程序",
+      "生成海报插图",
+      "推荐晚餐餐厅",
+      "只修改数据库索引，没有语言代码",
+      "只设计框架组件路由，不改语言配置",
+      "重写营销标题",
+      "生成音频配乐",
+      "只翻译包含该技术名称的说明文字，不修改或评审任何程序"
+    ]
   }
 }