@bovinphang/craft-common 1.0.1 → 2.0.0

package/localized/zh-CN/skills/cc-tauri-project-standard/references/common/engineering-practices.sources.json

@@ -0,0 +1,377 @@
+{
+  "schemaVersion": 1,
+  "sources": [
+    {
+      "id": "google-review",
+      "publisher": "Google",
+      "title": "Code review standard",
+      "url": "https://google.github.io/eng-practices/review/reviewer/standard.html",
+      "section": "Engineering principles and code health",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public guidance; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Use evidence and project standards; personal preference alone is not a blocker."
+    },
+    {
+      "id": "ms-playbook",
+      "publisher": "Microsoft ISE",
+      "title": "Test planning",
+      "url": "https://microsoft.github.io/code-with-engineering-playbook/automated-testing/test-planning/",
+      "section": "Risk, test scope and responsibilities",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living ISE playbook; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Team practice, not a company-wide mandate; retain existing tools."
+    },
+    {
+      "id": "ms-faults",
+      "publisher": "Microsoft ISE",
+      "title": "Fault injection testing",
+      "url": "https://microsoft.github.io/code-with-engineering-playbook/automated-testing/fault-injection-testing/",
+      "section": "Controlled failure and observations",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living ISE playbook; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Run scoped, controlled failures; do not infer production reliability from a small example."
+    },
+    {
+      "id": "google-ts",
+      "publisher": "Google",
+      "title": "TS/JS style guide",
+      "url": "https://google.github.io/styleguide/tsguide.html",
+      "section": "Environment caveat; types and exceptions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Public guide; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Google explicitly notes internal constraints differ; no blanket ban overriding a justified project convention."
+    },
+    {
+      "id": "typescript-publishing",
+      "publisher": "TypeScript",
+      "title": "Publishing declaration files",
+      "url": "https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html",
+      "section": "Types and declaration dependencies",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living handbook; check installed compiler/module resolution",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Validate the actual packed consumer; do not upgrade compiler or module mode on this basis."
+    },
+    {
+      "id": "rust-api",
+      "publisher": "Rust library team",
+      "title": "Rust API Guidelines",
+      "url": "https://rust-lang.github.io/api-guidelines/",
+      "section": "Type safety, dependability and future proofing",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living recommendations; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Guidance rather than language law; preserve edition and MSRV."
+    },
+    {
+      "id": "tokio-join",
+      "publisher": "Tokio project",
+      "title": "JoinHandle",
+      "url": "https://docs.rs/tokio/latest/tokio/task/struct.JoinHandle.html",
+      "section": "Drop, abort and completion",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed 1.54.1; project runtime/version determines applicability",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Tokio-specific mechanics only when Tokio is already used; no new runtime dependency."
+    },
+    {
+      "id": "uber-go",
+      "publisher": "Uber",
+      "title": "Go Style Guide",
+      "url": "https://github.com/uber-go/guide/blob/master/style.md",
+      "section": "Errors, interfaces and goroutine lifetime",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living master; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Do not import Uber dependencies or turn buffer-size style into a correctness theorem."
+    },
+    {
+      "id": "go-context",
+      "publisher": "Go project",
+      "title": "context package",
+      "url": "https://pkg.go.dev/context",
+      "section": "Cancellation propagation and ownership",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Standard library; check owning go.mod/toolchain",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "A cancellation signal alone does not confirm worker exit."
+    },
+    {
+      "id": "google-java",
+      "publisher": "Google",
+      "title": "Java Style Guide",
+      "url": "https://google.github.io/styleguide/javaguide.html",
+      "section": "Source structure and exception handling",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public style; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Naming/layout follows local standard; style is distinct from runtime correctness."
+    },
+    {
+      "id": "oracle-resources",
+      "publisher": "Oracle",
+      "title": "Try-with-resources",
+      "url": "https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html",
+      "section": "Closing resources and suppressed exceptions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "JDK8 tutorial; not a source for newer runtime features",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Preserve primary cause and borrowed-resource ownership; check actual API contract."
+    },
+    {
+      "id": "java-executor",
+      "publisher": "Oracle",
+      "title": "ExecutorService",
+      "url": "https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/ExecutorService.html",
+      "section": "Shutdown, termination and awaitTermination",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Java SE17 documentation",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Check target JDK; no automatic virtual-thread or JDK migration."
+    },
+    {
+      "id": "google-python",
+      "publisher": "Google",
+      "title": "Python Style Guide",
+      "url": "https://google.github.io/styleguide/pyguide.html",
+      "section": "Imports, exceptions and mutable state",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public guide; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Keep current formatter/type checker and library responsibilities."
+    },
+    {
+      "id": "python-asyncio",
+      "publisher": "Python project",
+      "title": "Coroutines and tasks",
+      "url": "https://docs.python.org/3/library/asyncio-task.html",
+      "section": "Cancellation and task ownership",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed 3.15.2; feature availability follows project Python",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Newer TaskGroup/timeout features require a supported project version; no upgrade implied."
+    },
+    {
+      "id": "cert-c",
+      "publisher": "CMU SEI",
+      "title": "MEM00-C allocation and release",
+      "url": "https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/recommendations/memory-management-mem/mem00-c/",
+      "section": "MEM00-C memory responsibility",
+      "checkedAt": "2026-11-08",
+      "versionScope": "2016-edition standard family; MEM00-C is a recommendation",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Do not label recommendations as mandatory CERT rules or apply C++ ownership machinery to pure C."
+    },
+    {
+      "id": "cpp-core",
+      "publisher": "C++ Core Guidelines editors",
+      "title": "C++ Core Guidelines",
+      "url": "https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines",
+      "section": "Resource and lifetime interfaces",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page dated 2026-06-14, living release0.8",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Adapt to existing exception policy and compiler; borrowing does not imply ownership."
+    },
+    {
+      "id": "google-cpp",
+      "publisher": "Google",
+      "title": "C++ Style Guide",
+      "url": "https://google.github.io/styleguide/cppguide.html",
+      "section": "Exceptions and project consistency",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public guide; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Its exception/standard policy is not universal; preserve the owning project policy and C ABI."
+    },
+    {
+      "id": "ms-sal",
+      "publisher": "Microsoft",
+      "title": "Understanding SAL",
+      "url": "https://learn.microsoft.com/en-us/cpp/code-quality/understanding-sal?view=msvc-170",
+      "section": "Parameter preconditions and output guarantees",
+      "checkedAt": "2026-11-08",
+      "versionScope": "MSVC170 documentation view",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "SAL is an optional toolchain-specific expression, not a portable mandatory annotation."
+    },
+    {
+      "id": "aws-retry",
+      "publisher": "AWS",
+      "title": "Timeouts, retries and backoff with jitter",
+      "url": "https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/",
+      "section": "Timeouts, bounded retries and retry amplification",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Article dated 2019-12-05; official Builder Center redirect",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Retry only semantically safe operations within a total budget; failure classes alone do not grant write replay."
+    },
+    {
+      "id": "aws-idempotency",
+      "publisher": "AWS",
+      "title": "Making retries safe with idempotent APIs",
+      "url": "https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/",
+      "section": "Caller intent, duplicate requests and atomic recording",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Builders Library; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "A process-local example does not establish database/multi-process exactly-once."
+    },
+    {
+      "id": "react-effects",
+      "publisher": "React project",
+      "title": "useEffect",
+      "url": "https://react.dev/reference/react/useEffect",
+      "section": "Cleanup and fetching race conditions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed React19.3; use installed project API",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Abort and stale-result checks complement each other; no React upgrade implied."
+    },
+    {
+      "id": "react-act",
+      "publisher": "React project",
+      "title": "act",
+      "url": "https://react.dev/reference/react/act",
+      "section": "Applying updates before assertions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed React19.3; verify sample versions",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "DOM simulation is not browser E2E or native desktop execution."
+    },
+    {
+      "id": "vue-watchers",
+      "publisher": "Vue project",
+      "title": "Watchers",
+      "url": "https://vuejs.org/guide/essentials/watchers.html",
+      "section": "Side-effect cleanup",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Vue3; onWatcherCleanup requires3.5+ and synchronous registration",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Use supported callback cleanup on older Vue3; no framework migration."
+    },
+    {
+      "id": "tauri-permissions",
+      "publisher": "Tauri project",
+      "title": "Permissions",
+      "url": "https://v2.tauri.app/security/permissions/",
+      "section": "Command allow/deny and capability scope",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Tauri2 docs; check installed version/configuration",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Rust command-unit tests do not activate webview permissions or prove packaged GUI security."
+    },
+    {
+      "id": "electron-security",
+      "publisher": "Electron project",
+      "title": "Security",
+      "url": "https://www.electronjs.org/docs/latest/tutorial/security",
+      "section": "IPC sender checks and renderer trust",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living docs; match installed Electron",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Handler tests do not prove sandbox/context isolation is active in a packaged app."
+    },
+    {
+      "id": "spring-tests",
+      "publisher": "Spring project",
+      "title": "Testing Spring Boot applications",
+      "url": "https://docs.spring.io/spring-boot/3.5/reference/testing/spring-boot-applications.html",
+      "section": "Test slices and application tests",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Boot3.5 docs observed3.5.16; preserve sample/project versions",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Test scope matters; MVC tests do not establish live DB/transaction or deployment behavior."
+    },
+    {
+      "id": "fastapi-lifespan",
+      "publisher": "FastAPI project",
+      "title": "Lifespan events",
+      "url": "https://fastapi.tiangolo.com/advanced/events/",
+      "section": "Acquire and release application resources",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living FastAPI documentation; match pinned dependencies",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Use actual lifespan execution in tests; import does not own a live connection."
+    },
+    {
+      "id": "gin-binding",
+      "publisher": "Gin project",
+      "title": "Binding",
+      "url": "https://gin-gonic.com/en/docs/binding/",
+      "section": "Binding errors and validation",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living Gin documentation; match pinned module",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Writing/aborting a response does not replace explicit control-flow return in the current handler."
+    },
+    {
+      "id": "axum-extractors",
+      "publisher": "Axum project",
+      "title": "Extractors",
+      "url": "https://docs.rs/axum/latest/axum/extract/",
+      "section": "Extractor order and rejections",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Latest route observed0.8.9; fixed0.8.9 route unavailable via browser tool",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Pinned existing example is authoritative for compilation; do not assume source signatures across releases."
+    },
+    {
+      "id": "drogon-filters",
+      "publisher": "Drogon project",
+      "title": "Middleware and Filter",
+      "url": "https://github.com/drogonframework/drogon/wiki/ENG-05-Middleware-and-Filter",
+      "section": "Filter callbacks and continuation",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living wiki; match compiled example version",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Synthetic role headers are not authentication; callback lifetime must follow actual ownership."
+    },
+    {
+      "id": "node-typescript",
+      "publisher": "Node.js project",
+      "title": "Modules: TypeScript",
+      "url": "https://nodejs.org/api/typescript.html",
+      "section": "Type-stripping history, enabling, and separate type checking",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed26.13.0; sample>=22.18, actual24.14.1 tested; product Node>=22 unchanged",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Native stripping is not type checking and ignores tsconfig. Missing sample capability is MISSING, not a product runtime upgrade."
+    }
+  ]
+}

package/localized/zh-CN/skills/cc-tauri-project-standard/references/engineering-practices.md

@@ -0,0 +1,73 @@
+---
+practiceCards:
+  - id: "cc-tauri-project-standard:ipc-validation"
+    level: "required"
+    sourceIds: ["tauri-permissions"]
+    caseIds: ["EP-TS-01","EP-IPC-01"]
+    evidence: "review-only"
+  - id: "cc-tauri-project-standard:cancellation-cleanup"
+    level: "conditional"
+    sourceIds: ["tokio-join","tauri-permissions"]
+    caseIds: ["EP-RS-01","EP-IPC-01"]
+    evidence: "review-only"
+---
+
+# 本入口工程决策
+
+先定位项目角色、工具链及已有约定，再按需读取[公共原则](common/engineering-practices.md)。下列条件仅约束当前语言/场景；结构检查不证明全部语义或实际运行。
+
+<a id="cc-tauri-project-standard:ipc-validation"></a>
+## 注册命令不等于安全授权
+
+级别: required
+
+### 风险
+存在capability文件时，实际选中的命令/窗口授权仍可能错误。
+
+### 适用
+适用于真实Tauri2命令/插件，检查已安装minor及选中应用配置。
+
+### 决策
+核对invoke注册、生成的应用命令权限、已选/重叠capability、窗口标签及远端来源；Rust副作用前校验有界类型输入和业务权限。
+
+### 例外
+可信根路径由应用拥有，不由渲染端提供；仅canonicalize后open不能防对手替换祖先；不套Electron API。
+
+### 正反示意
+正例：受限命令校验应用拥有根下路径。反例：渲染端提供任意根，把注册当授权。
+
+### 验证
+运行已有Rust core测试并检查真实生成/选中授权；运行时权限激活和GUI需独立NOT RUN记录。
+
+### 来源
+tauri-permissions — [来源与适用限制](common/engineering-practices.sources.json).
+
+证据标识: EP-TS-01, EP-IPC-01; review-only.  执行状态及覆盖范围见实际记录；关联ID不证明该卡全部语义。
+
+<a id="cc-tauri-project-standard:cancellation-cleanup"></a>
+## 窗口关闭协调核心任务及资源
+
+级别: conditional
+
+### 风险
+窗口关闭后Rust任务或sidecar资源可能继续活动。
+
+### 适用
+命令启动工作，或调用外仍持有文件/池/sidecar时适用。
+
+### 决策
+明确应用/核心任务拥有者，停接单、取消/排空并等待完成，再释放依赖；尽量把阻塞及guard移出UI关键挂起区。
+
+### 例外
+调用方取消可能不停止原生写，应显式表示未完成/部分提交，不强制升级运行时或依赖。
+
+### 正反示意
+正例：核心向应用报告完成/未完成关闭。反例：丢弃UI等待方就认为原生工作全停。
+
+### 验证
+用实际核心/运行时事件及目标进程检查；已有路径测试和Node IPC证据不证明Tauri关闭或签名包。
+
+### 来源
+tokio-join, tauri-permissions — [来源与适用限制](common/engineering-practices.sources.json).
+
+证据标识: EP-RS-01, EP-IPC-01; review-only.  执行状态及覆盖范围见实际记录；关联ID不证明该卡全部语义。

package/localized/zh-CN/skills/cc-tauri-project-standard/references/practice.md

@@ -0,0 +1,20 @@
+# Tauri 实践
+
+- 先读 `tauri.conf.json`、`Cargo.toml`、锁、`build.rs`、capabilities、permissions 和 Web 构建配置，在混合仓库中明确 UI/core 对应关系。
+- Tauri 2 自定义应用 command 同时检查 `AppManifest::commands`、权限生成和 `invoke_handler`。仅存在 capability 文件不代表注册的应用命令已受限；检查实际选中的 capability、重叠授权、窗口 label 和远程访问。
+- Rust 接收有界类型输入，校验路径及业务授权，返回稳定公开错误并明确序列化契约。可信根不能来自 renderer。[核心案例](../examples/minimal/core/src/lib.rs)以应用拥有的根执行真实路径包含检查。
+- 示例假设目录由应用控制；先 canonicalize 再 open 不能防御本地攻击者并发替换祖先目录。存在该威胁时应采用平台句柄或相对目录句柄打开机制。
+- 使用尽量小的 `State`，明确池、任务和文件的所有者与退出释放顺序。按实际运行时和工作量决定异步/阻塞边界，不阻塞 UI，不跨 await 持有不适当的锁。
+- 分别检查插件、sidecar、命令参数、CSP 和导航权限；新窗口不能悄悄继承宽泛授权。
+- 保持目标平台配置。Linux 系统库、Windows WebView2、macOS 签名/entitlements 及 updater 签名需要各自真实环境证据。
+
+## 官方版本参考
+
+2026-11-08 核验 Tauri **2** 文档；版本敏感接口必须匹配工程锁定的 minor 与插件版本：
+
+- [命令与调用契约](https://v2.tauri.app/develop/calling-rust/)。
+- [能力与应用命令权限生成](https://v2.tauri.app/security/capabilities/)。
+- [权限定义](https://v2.tauri.app/security/permissions/)。
+- [运行时权限判定](https://v2.tauri.app/security/runtime-authority/)。
+
+案例将纯 Rust core 拆为独立 crate，以便离线验证边界，不把核心测试冒充 Tauri 运行时或 GUI 验证。

package/localized/zh-CN/skills/cc-tauri-project-standard/references/verification.md

@@ -0,0 +1,18 @@
+# 验证边界
+
+在[最小应用目录](../examples/minimal/README.md)执行：
+
+```sh
+cargo test --manifest-path core/Cargo.toml --offline --locked --features defective
+cargo test --manifest-path core/Cargo.toml --offline --locked
+```
+
+首条命令故意选择缺陷函数，应在相同的目录穿越/绝对路径断言中失败；正常版本应同时通过合法文件行为。Unix 另测符号链接越界。编译器或依赖缺失属于 MISSING，不能当业务 RED；构建产物放在分发目录外。
+
+| 层次 | 证据与限制 |
+| --- | --- |
+| Rust command core | 真实 Cargo 测试证明非法路径不能返回根外数据，无需 GUI。 |
+| Tauri 集成 | 使用已准备的 Tauri 2 工具链启动应用，通过真实 invoke 检查允许/拒绝的窗口与 capability；核心单测不证明权限激活。 |
+| 桌面发布 | 在每个目标平台验证 UI 流程、bundle、安装更新、清理及签名，不能用文本检查替代。 |
+
+2026-11-08 开发证据：Windows Rust 1.96.0 的核心测试已观察真实 RED→GREEN。Tauri 依赖构建、WebView 权限激活、GUI、签名及平台包均为 **NOT RUN**。系统库或依赖缺失须如实记录，不隐式下载。

package/localized/zh-CN/skills/cc-typescript-project-standard/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: cc-typescript-project-standard
+description: 用于TypeScript 工程配置、模块解析、公共类型、声明文件、包导出、类型收窄或泛型契约需要设计审查，适用于应用、SDK、CLI、桌面进程与库。
+---
+
+# TypeScript 项目规范
+
+本入口面向库、CLI、桌面核心及服务中的语言工程；应用角色由实际子工程证据决定，不由前端/后端产品名决定。
+
+## 用途
+
+统一 TypeScript 层的工程配置、类型边界和发布产物规则。适用于前端应用、组件库、SDK、CLI、monorepo package 和纯 TypeScript 工具库，但不接管 React、Vue、Next.js、Nuxt 或 Vite 的框架架构职责。
+
+## 流程
+
+1. 识别 TypeScript 上下文
+   - 应用项目：优先检查 `tsconfig` 分层、strictness、路径别名、类型检查脚本和框架生成类型。
+   - 组件库或 SDK：优先检查 public API、声明文件、package exports、peer dependencies 类型边界和发布前 pack 校验。
+   - CLI 或 Node 工具：优先检查 Node 目标版本、ESM/CJS 策略、`moduleResolution`、shebang 产物和 `process.env` 类型边界。
+   - Monorepo package：优先检查 project references、composite build、包间导入边界和 workspace 路径别名是否泄漏到发布产物。
+   - React、Vue、Next.js、Nuxt 等框架的组件架构、路由组织和状态管理归对应框架 skill；本流程只处理跨框架 TypeScript 契约和工程边界。
+
+2. 收敛 `tsconfig`
+   - 新代码优先 `strict` 并保留已有检查，不为掩盖缺陷关闭 `noImplicitAny` 或 `strictNullChecks`。`exactOptionalPropertyTypes` 是独立选项；有依据时以局部、兼容迁移引入更严格配置。
+   - 按运行环境选择 `target`、`lib`、`module` 和 `moduleResolution`；浏览器应用、Node 脚本、库包不要共用一份含混配置。
+   - 将基础配置、应用配置、测试配置和构建声明配置拆开，避免测试全局类型污染生产代码。
+   - 路径别名必须同时被 TypeScript、bundler、test runner 和发布产物理解；库包不得发布无法解析的源码别名。
+
+3. 设计类型边界
+   - 外部输入、DTO、领域模型、UI view model、组件 props 和工具函数 API 分层命名。
+   - public API 的参数和返回值显式标注，内部局部变量优先依赖推断。
+   - 外部数据先以 `unknown` 接收，再通过 schema 或 type guard 收窄。
+   - 复杂泛型、判别联合、DTO 映射、类型守卫和类型测试加载 [类型安全参考](references/type-safety.md)；需要高级模式时加载 [类型安全模式](references/type-safety-patterns.md)。
+
+4. 固定发布与声明产物
+   - 库包必须确认 `package.json` 的 `exports`、`types`、`files` 和实际构建产物一致。
+   - 不默认双包发布；只有明确消费方需要时才同时产出 ESM/CJS，并验证类型入口不分叉。
+   - 通过 `tsc --emitDeclarationOnly`、构建工具声明插件或 API extractor 产出 `.d.ts`，并在发布前检查声明文件可被消费方解析。
+   - 不把测试、fixture、内部工具、未稳定类型或私有路径暴露到 package exports。
+
+5. 验证 TypeScript 质量
+   - 优先使用仓库已有脚本，如 `typecheck`、`build`、`test`、`lint` 和 package pack dry-run。
+   - Vite、Next、Nuxt 等构建不等于完整类型检查；CI 必须有独立 typecheck 或等效验证。
+   - 类型改动影响 public API 时补类型测试、编译期断言或消费方 fixture。
+
+## 约束
+
+- 不用 `any`、无守卫非空断言或宽泛 `as` 掩盖未经验证的边界。合理的 `skipLibCheck` 依赖政策与检查自身公共API有别，需记录其限制。
+- 不在应用代码中依赖发布包私有深层路径。
+- 不把框架目录结构、组件分层、路由组织或状态管理决策放进本流程；这些交给对应框架或专项流程。
+- 不让生成类型、测试类型或 Node-only 类型污染浏览器运行代码。
+- 不发布只能在源码仓库内解析的路径别名、ambient 声明或隐式全局类型。
+
+## 预期输出
+
+输出应包含 TypeScript 上下文判断、关键 `tsconfig`/package 类型入口建议、类型边界方案、声明文件或 public API 风险、验证命令。完成后项目应能独立 typecheck，公开类型可被消费方解析，类型安全问题有明确收窄或建模方案。
+
+## 工程实践
+
+按当前任务读取[本入口工程细则](references/engineering-practices.md)，再按链接选择公共原则。规则级别与例外以实际项目契约为准；不因产品前后端标签限制语言或职责。

package/localized/zh-CN/skills/cc-typescript-project-standard/examples/engineering/README.md

@@ -0,0 +1,7 @@
+# 外部输入边界 — EP-TS-01
+
+将此目录复制到可写临时位置。样例自有Node >=22.18目标（原生类型擦除），不升级父项目。显式准备：pnpm install --ignore-scripts --frozen-lockfile，然后pnpm typecheck。PowerShell设$env:CRAFT_ENGINEERING_DEFECTIVE为1，运行pnpm test，非法输入命名断言应失败；设为0或移除变量后同组两个测试通过。POSIX可在测试命令前设置同名环境变量。
+
+回调记录校验前后的真实副作用，缺陷分支故意以断言替代校验；默认受保护。这里不验证付款服务、浏览器、异步状态及声明发布。仅依赖本目录源码和已声明工具，node_modules/build/log应留在可写副本。
+
+[Node.js 类型擦除历史与限制](https://nodejs.org/api/typescript.html)：运行时类型擦除与显式 TypeScript 类型检查分开。

package/localized/zh-CN/skills/cc-typescript-project-standard/examples/engineering/boundary.test.ts

@@ -0,0 +1,16 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { acceptAmount } from "./input.ts";
+
+test("EP-TS-01 rejects invalid input before any effect", () => {
+  const effects: number[] = [];
+  for (const input of [{ amount: "10" }, { amount: -1 }, { amount: Number.MAX_SAFE_INTEGER + 1 }, null]) {
+    assert.throws(() => acceptAmount(input, amount => effects.push(amount)), /invalid amount/);
+    assert.deepEqual(effects, []);
+  }
+});
+test("EP-TS-01 accepts a valid input exactly once", () => {
+  const effects: number[] = [];
+  acceptAmount({ amount: 10 }, amount => effects.push(amount));
+  assert.deepEqual(effects, [10]);
+});

package/localized/zh-CN/skills/cc-typescript-project-standard/examples/engineering/input.ts

@@ -0,0 +1,12 @@
+/** Test switch only; normal use always validates the external boundary. */
+export function acceptAmount(value: unknown, effect: (amount: number) => void): void {
+  if (process.env.CRAFT_ENGINEERING_DEFECTIVE === "1") {
+    effect((value as { amount: number }).amount);
+    return;
+  }
+  if (typeof value !== "object" || value === null || !("amount" in value)
+      || typeof value.amount !== "number" || !Number.isSafeInteger(value.amount) || value.amount <= 0) {
+    throw new TypeError("invalid amount");
+  }
+  effect(value.amount);
+}

package/localized/zh-CN/skills/cc-typescript-project-standard/examples/engineering/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "engineering-typescript-boundary-example",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "engines": { "node": ">=22.18.0" },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test --test-reporter=tap boundary.test.ts"
+  },
+  "devDependencies": { "typescript": "5.9.3", "@types/node": "22.20.5" }
+}

package/localized/zh-CN/skills/cc-typescript-project-standard/examples/engineering/pnpm-lock.yaml

@@ -0,0 +1,39 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    devDependencies:
+      '@types/node':
+        specifier: 22.20.5
+        version: 22.20.5
+      typescript:
+        specifier: 5.9.3
+        version: 5.9.3
+
+packages:
+
+  '@types/node@22.20.5':
+    resolution: {integrity: sha512-U2+DNr+wSjpsTS/wZGYHq7GcwfuSmKiKvoPvK22zwTlRhU91yOniN4qRR5KhIjvif7ysw/dz/hKmfDH0Ris4aA==}
+
+  typescript@5.9.3:
+    resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  undici-types@6.21.0:
+    resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
+
+snapshots:
+
+  '@types/node@22.20.5':
+    dependencies:
+      undici-types: 6.21.0
+
+  typescript@5.9.3: {}
+
+  undici-types@6.21.0: {}

package/localized/zh-CN/skills/cc-typescript-project-standard/examples/engineering/pnpm-workspace.yaml

@@ -0,0 +1 @@
+packages: []