@namewta/speculo 0.7.4 → 0.7.5

package/template/skills/engineering-standards-builder/references/typescript/00-detection-and-scope.md

@@ -0,0 +1,58 @@
+# TypeScript / JavaScript：检测、版本与作用域
+
+## 触发信号
+
+至少交叉验证两类信号：
+
+- `package.json`、Workspace 配置和锁文件；
+- `tsconfig*.json`、`jsconfig.json`；
+- `.ts`、`.tsx`、`.mts`、`.cts`、`.js`、`.jsx`、`.vue` 源码；
+- CI 中的 package manager、编译、Lint、测试和构建命令；
+- 框架入口、bundler 配置和 package exports。
+
+只有依赖但无源码使用时记为依赖信号。根 `package.json` 不能自动把所有 Workspace package 判定为同一框架或运行时。
+
+## 版本事实
+
+记录而不猜测：
+
+- Node/Bun/Deno 等运行时版本来源；
+- TypeScript 版本与 `compilerOptions`；
+- package manager 与锁文件；
+- ESM/CJS 声明；
+- 浏览器、Node、Worker、测试、Electron 等环境分别使用的配置；
+- React/Vue 和构建工具的大版本。
+
+版本来源优先级：锁定工具链配置、CI、manifest、锁文件、文档。不得把 Builder 所在环境版本当作项目版本。
+
+## Scope
+
+常见 scope：
+
+```text
+module:apps/web
+module:packages/sdk
+language:typescript
+runtime:browser
+runtime:node
+framework:vue
+framework:react
+```
+
+`.vue` 中的 TypeScript 属于 Vue 模块；Node 构建脚本不应继承浏览器 DOM 规则；测试配置可有独立编译环境。
+
+## 访谈触发
+
+仅在证据冲突时询问：
+
+- JavaScript 存量是否迁移到 TypeScript；
+- strict 提升采用全量、模块阶段还是新代码 Ratchet；
+- 多运行环境是否拆分 tsconfig；
+- ESM/CJS 目标与发布兼容范围；
+- typed linting 的作用域和性能预算。
+
+## 官方依据
+
+- [TypeScript TSConfig](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html)
+- [TypeScript Project References](https://www.typescriptlang.org/docs/handbook/project-references.html)
+- [Node.js packages: modules](https://nodejs.org/api/packages.html)

package/template/skills/engineering-standards-builder/references/typescript/01-language-and-type-system.md

@@ -0,0 +1,49 @@
+# TypeScript / JavaScript：语言与类型系统
+
+## 编译边界
+
+- 每个运行环境使用与其全局对象、module resolution 和输出目标一致的配置；必要时以共享 base + 独立 app/test/tooling tsconfig 组织。
+- 新项目默认采用当前版本可支持的严格检查；存量项目先测量，再按模块或错误基线 Ratchet。
+- `skipLibCheck`、宽松选项和声明补丁记录原因、scope 与删除条件。
+- 不为修复局部错误全局降低 strictness。
+
+## 可信边界
+
+- 外部 JSON、环境变量、消息、DOM dataset、存储和第三方 SDK 返回值先视为 `unknown`，在边界验证并缩窄。
+- `any` 只允许在无法建模的兼容边界短暂存在；使用位置、风险和替换条件必须明确。
+- 类型断言不能代替运行时验证；双重断言和非空断言只允许有可证明不变量的局部位置。
+- 使用判别联合、精确字面量、泛型约束和领域类型表达非法状态。
+- 不用宽泛索引签名抹去已知字段和错误拼写。
+
+## 类型设计
+
+- 类型从 public contract 和领域不变量出发，不为“减少几行”制造晦涩元编程。
+- `interface` 与 `type` 遵循 scope 内主导实践；只有扩展/声明合并等语义差异需要决策，不把偏好升级为 MUST。
+- 公共泛型有明确约束和推断体验；避免让调用者重复提供可推断类型。
+- `readonly`、不可变集合或复制边界用于表达所有权，不无条件深只读全部对象。
+- 枚举选择遵循现有序列化和编译目标；不要在不了解运行时产物时强制切换 `enum`、const object 或 union。
+
+## JavaScript scope
+
+纯 JavaScript 模块仍适用：
+
+- 使用 JSDoc、`checkJs` 或 schema 获得边界类型；
+- 不把迁移中的 `.js` 文件假装成已严格类型化；
+- TypeScript 迁移按目录、入口或公共 API 分阶段；
+- package exports 和运行时行为优先于类型表面统一。
+
+## 规则输出示例
+
+```text
+Scope: module:packages/api-client
+Level: MUST
+Source: repository-fact + user-decision
+Rule: 网络响应在 adapter 边界验证，业务层不得直接断言为领域类型。
+Verification: typecheck；响应 schema 测试；review 搜索未经收窄的 unknown/any。
+```
+
+## 官方依据
+
+- [TypeScript `strict`](https://www.typescriptlang.org/tsconfig/strict.html)
+- [TypeScript narrowing](https://www.typescriptlang.org/docs/handbook/2/narrowing.html)
+- [TypeScript declaration reference](https://www.typescriptlang.org/docs/handbook/declaration-files/by-example.html)

package/template/skills/engineering-standards-builder/references/typescript/02-modules-packages-and-runtime-boundaries.md

@@ -0,0 +1,49 @@
+# TypeScript / JavaScript：模块、包与运行环境边界
+
+## Package 与公开入口
+
+- Workspace package 只通过 `package.json` exports、声明的入口或项目确认的 public barrel 暴露 API。
+- 跨 package 深导入内部路径默认禁止；内部测试若需要白盒入口，应建立显式 test-only contract。
+- `main`、`module`、`types`、`exports`、`imports`、`bin` 与实际构建产物保持一致。
+- package 内部可用相对路径或受控 alias；alias 不得绕过 Workspace 边界或发布时失效。
+- 类型导入在项目工具支持时使用 `import type`，避免意外运行时依赖和循环。
+
+## Barrel
+
+barrel 不是通用默认。只有在以下条件成立时采用：
+
+- 代表稳定 public surface；
+- 不造成隐藏副作用、初始化顺序问题或循环；
+- bundler、测试和 Node resolution 行为已验证；
+- 不鼓励同 package 内部绕行 public 入口形成自循环。
+
+“每个目录都建 `index.ts`”不得作为无证据强制规则。
+
+## ESM / CJS
+
+- 依据项目 `type`、扩展名、tsconfig、bundler 和消费者支持范围确定。
+- Node ESM 的路径扩展名、条件 exports 和动态 import 按真实运行环境验证。
+- 库同时发布多格式时，测试每个导出条件和类型解析；避免 dual-package state hazard。
+- 测试工具与生产 runtime 的 module 模式不一致时显式拆分配置。
+
+## 多运行环境
+
+浏览器、Node、Web Worker、Service Worker、Electron main/preload/renderer、测试和构建脚本应拥有清晰边界：
+
+- 不共享错误的全局类型；
+- 平台 API 通过 adapter 注入；
+- 环境变量只在对应构建/运行边界读取；
+- 共享包不得隐式依赖 DOM 或 Node globals，除非 contract 明确；
+- 不把 bundler 能解析等同于 Node/消费者能解析。
+
+## 循环与副作用
+
+- module 顶层副作用最小化；注册、polyfill 和启动逻辑放在明确入口。
+- 循环依赖先修职责和依赖方向，不依赖打包顺序“碰巧可用”。
+- 构建/测试通过不代表 lazy import、SSR 和生产 chunk 初始化顺序安全；高风险边界增加运行测试。
+
+## 官方依据
+
+- [TypeScript modules reference](https://www.typescriptlang.org/docs/handbook/modules/reference.html)
+- [Node.js packages](https://nodejs.org/api/packages.html)
+- [Node.js ECMAScript modules](https://nodejs.org/api/esm.html)

package/template/skills/engineering-standards-builder/references/typescript/03-functions-async-errors-resources.md

@@ -0,0 +1,42 @@
+# TypeScript / JavaScript：函数、异步、错误与资源
+
+## 函数合同
+
+- 参数表达必需输入；可选项较多或布尔组合复杂时使用具名 options。
+- 纯计算与 I/O、状态变更、日志和框架生命周期分离。
+- callback、Promise、stream、iterator 和 event emitter 的失败与取消语义清楚。
+- public function 的返回类型在有助于稳定 API 时显式声明；局部实现优先可靠推断。
+
+## Promise 与取消
+
+- 不遗留 floating Promise；明确 `await`、return、批量等待或有监督的后台任务。
+- 并发批处理定义最大并发度、失败策略、顺序需求和部分成功语义。
+- 支持取消的 I/O 优先传播 `AbortSignal`；超时由调用边界定义并保留原始 cause。
+- 忽略过期响应、组件卸载后的写入和竞争覆盖；请求所有者负责清理。
+- `Promise.all`、`allSettled`、race 等按失败合同选择，不为简短牺牲语义。
+
+## Error
+
+- 抛出/返回 `Error` 或项目定义错误类型，而不是裸字符串。
+- catch 变量视为 `unknown`；只在能恢复、映射或增加边界上下文时捕获。
+- 使用 `cause` 或项目现有机制保留原始错误。
+- 日志、用户消息、HTTP/CLI 错误码分离；不重复在每一层记录同一错误。
+- Node callback、event emitter `error`、stream 和 process rejection 都有明确处理边界。
+
+## 资源
+
+- timer、event listener、subscription、stream、socket、worker、child process、temporary file 和 object URL 都有所有者与清理路径。
+- 使用平台提供的结构化清理能力；`using`/`Disposable` 只有项目编译目标和依赖完整支持时才采用。
+- 测试验证取消、超时、重复关闭、初始化部分失败和进程退出。
+
+## JavaScript interop
+
+- 回调式 API 封装为 Promise 时只 settle 一次并正确转发 error。
+- `this`、prototype、Proxy、动态属性和第三方未类型化对象限制在 adapter。
+- 不通过无边界 monkey patch 修改全局或第三方对象。
+
+## 官方依据
+
+- [MDN AbortController](https://developer.mozilla.org/docs/Web/API/AbortController)
+- [Node.js error handling](https://nodejs.org/api/errors.html)
+- [TypeScript release notes and resource management](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html)

package/template/skills/engineering-standards-builder/references/typescript/04-testing-tooling-quality-gates.md

@@ -0,0 +1,51 @@
+# TypeScript / JavaScript：测试、工具链与质量门禁
+
+## 工具事实
+
+从仓库识别并复用：
+
+- package manager 与锁文件；
+- formatter：Prettier、Biome 或其他；
+- lint/static analysis：ESLint、typescript-eslint、Biome、Oxlint 等；
+- typecheck：`tsc`、`vue-tsc`、framework build；
+- unit/component：Vitest、Jest、Node test runner 等；
+- browser/E2E：Playwright、Cypress 等；
+- bundler/build：Vite、Webpack、Rollup、esbuild、framework CLI。
+
+不得仅因为 Builder 熟悉某工具就引入或替换工具。
+
+## Type-aware linting
+
+- 先区分 syntax-only 和 type-aware rules；后者更强但有项目加载和性能成本。
+- 使用与 Workspace/tsconfig 架构匹配的 parser project 配置；避免单一巨型 config 意外加载整个 Monorepo。
+- 生成文件、配置脚本和不同 runtime 可有有理由的 override。
+- rule disable 最小化到行或文件，写明 WHY 与删除条件。
+
+## 测试
+
+- 纯逻辑单元测试不启动完整框架或浏览器。
+- DOM/组件测试验证公开交互和可访问输出，不读取私有状态。
+- 与 layout、原生事件、浏览器 API 或 hydration 强相关的行为使用真实浏览器测试。
+- package exports、ESM/CJS、SSR 和不同 runtime 使用消费方视角测试。
+- mock timer、network 和 module 时在每个测试后恢复；避免全局泄漏。
+
+## 门禁
+
+项目规范记录真实命令与工作目录，例如：
+
+```text
+format-check
+lint
+[type-aware lint]
+typecheck
+unit/component test
+browser/E2E test
+build/package
+```
+
+如果命令尚不存在，标记 planned，不伪装为当前门禁。
+
+## 官方依据
+
+- [typescript-eslint typed linting](https://typescript-eslint.io/getting-started/typed-linting/)
+- [TypeScript project references](https://www.typescriptlang.org/docs/handbook/project-references.html)

package/template/skills/engineering-standards-builder/references/typescript/README.md

@@ -0,0 +1,27 @@
+# TypeScript / JavaScript 适配器
+
+当 Project Inventory 为某个 scope 识别到 TypeScript 或 JavaScript 时读取本索引。先读语言核心，再按证据选择框架、运行时和应用类型。
+
+## 语言核心
+
+- [检测、版本与作用域](00-detection-and-scope.md)
+- [语言与类型系统](01-language-and-type-system.md)
+- [模块、包与运行环境边界](02-modules-packages-and-runtime-boundaries.md)
+- [函数、异步、错误与资源](03-functions-async-errors-resources.md)
+- [测试、工具链与质量门禁](04-testing-tooling-quality-gates.md)
+
+## 框架
+
+- [React](frameworks/react.md)
+- [Vue](frameworks/vue.md)
+
+## 运行时
+
+- [Browser](runtimes/browser.md)
+- [Node.js](runtimes/node.md)
+- [Electron](runtimes/electron.md)
+
+## 应用类型
+
+- [CLI](app-types/cli.md)
+- [发布库 / SDK](app-types/library.md)

package/template/skills/engineering-standards-builder/references/typescript/app-types/cli.md

@@ -0,0 +1,11 @@
+# TypeScript / JavaScript CLI
+
+- 入口只负责参数解析、配置、依赖装配、调用应用服务和映射退出码。
+- 参数、环境和配置文件在边界验证；优先结构化 argv API，不自行拼 shell。
+- stdout 为机器/用户主输出，stderr 为诊断；可脚本化输出提供稳定格式或 `--json`。
+- `--help`、版本、错误示例和非零退出码行为稳定且可测试。
+- 交互提示在非 TTY/CI 中有明确行为；不得永久等待隐藏输入。
+- signal、取消、临时文件、锁、子进程和 stream 在退出前清理。
+- 路径解析在明确 root 内，支持 Windows/macOS/Linux 的项目目标范围。
+- 命令 handler 可单元测试；真实进程测试覆盖 argv、cwd、env、stdio、exit code 和信号。
+- 发布时验证 `bin`、shebang、权限、exports、产物与最低 Node 版本。

package/template/skills/engineering-standards-builder/references/typescript/app-types/library.md

@@ -0,0 +1,11 @@
+# TypeScript / JavaScript 发布库与 SDK
+
+- public surface 只通过 package exports 和文档入口；内部路径不承诺兼容。
+- 明确支持的 runtime、module format、TypeScript/Node/browser 版本和平台。
+- 类型声明与运行时导出一一对应；使用消费方 fixture 测试解析和 tree-shaking/side effects。
+- package `sideEffects` 声明必须真实；顶层初始化不访问宿主全局或启动后台任务。
+- 依赖分类（dependencies/peer/dev/optional）反映运行时和消费者所有权。
+- 错误类型、取消、重试和 telemetry 默认为可控制；SDK 不静默记录敏感数据。
+- 破坏性 API、类型收窄、序列化与默认行为变化纳入版本和迁移说明。
+- ESM/CJS/条件 exports 仅发布实际验证的组合，避免同一包产生多份状态。
+- README 示例进入编译/运行测试，避免文档漂移。

package/template/skills/engineering-standards-builder/references/typescript/frameworks/react.md

@@ -0,0 +1,71 @@
+# React 规范适配器
+
+仅对 Project Inventory 明确识别为 React 的 scope 生成。React 与 Vue 共存时必须分别限定模块或路径。
+
+## 版本与应用模型
+
+先识别 React 大版本、客户端/SSR/SSG、framework router、Server/Client Component 边界、编译器和状态工具。不要把特定 Next/Remix/React Router 约定泛化为所有 React 项目。
+
+## 组件与纯净性
+
+- 新代码优先函数组件；存量 class component 以风险和迁移计划处理。
+- render 与 Hook 保持纯净：相同输入得到相同 JSX，不在 render 中发起副作用或修改外部状态。
+- props 为明确只读合同；组件不修改传入对象。
+- 展示、领域状态、I/O 编排和平台 adapter 在复杂度出现时分离，而不是按任意行数拆分。
+- component、Hook、context 和 provider 的命名遵循 scope 内一致实践。
+
+## Hook
+
+- Hook 只在 React 函数组件或自定义 Hook 顶层调用，不放在条件、循环、普通回调或事件分支。
+- 自定义 Hook 使用 `use` 前缀，公开输入、返回值、订阅、清理和并发语义。
+- 不用 Hook 隐藏不可追踪的全局写入。
+- 遵循项目当前启用的 React Hooks ESLint 规则；例外必须局部且有证明。
+
+## 状态与派生数据
+
+- 状态保持最小，能由 props/state 计算的值在 render 中计算或在测量后 memoize。
+- 状态放在拥有它的最小共同祖先；跨树共享才考虑 context 或项目既有 store。
+- reducer 用于多事件、多字段状态机，而不是简单值的仪式化包装。
+- context value 稳定性在有实际重渲染问题时优化；不要无条件包裹所有值。
+
+## Effect
+
+- Effect 用于同步外部系统：网络、订阅、DOM/平台 API、计时器、非 React widget。
+- 不用 Effect 计算派生数据、处理可直接在事件中完成的逻辑或同步两个可合并状态。
+- 依赖数组反映实际读取；不通过禁用 lint 隐藏陈旧闭包。
+- cleanup 必须撤销订阅、监听、timer、请求或外部资源；开发严格模式下 setup/cleanup 可重复执行仍正确。
+- 异步结果处理取消、过期响应和 unmount 后写入。
+
+## 性能
+
+- 先使用稳定边界、局部状态和纯组件；只在 profiler/指标证明后采用 memoization。
+- `memo`、`useMemo`、`useCallback` 是性能工具，不是语义保证。
+- 大列表采用分页/虚拟化；bundle 和懒加载遵循当前框架能力。
+
+## 可访问性与安全
+
+- 优先语义 HTML；交互元素具备键盘、焦点和可访问名称。
+- `dangerouslySetInnerHTML` 只接收经过可信边界处理的内容。
+- 客户端隐藏不能替代服务端授权。
+
+## 测试
+
+- 使用项目既有工具，测试用户可观察行为、DOM 和可访问交互。
+- 不以组件实例、私有 Hook 实现或脆弱 snapshot 为主要断言。
+- Effect、订阅和并发行为覆盖 cleanup、失败和竞争路径。
+- SSR/hydration、router 和 browser API 行为按实际运行环境测试。
+
+## 访谈触发
+
+- class → function 的迁移 scope；
+- Client/Server Component 和数据获取边界；
+- context 与既有 store 的职责；
+- Effect 债务采用立即修复或 Ratchet；
+- React compiler/memo 策略仅在项目实际采用时。
+
+## 官方依据
+
+- [React: Components and Hooks must be pure](https://react.dev/reference/rules/components-and-hooks-must-be-pure)
+- [React: Rules of Hooks](https://react.dev/reference/rules/rules-of-hooks)
+- [React: Synchronizing with Effects](https://react.dev/learn/synchronizing-with-effects)
+- [React: You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)

package/template/skills/engineering-standards-builder/references/typescript/frameworks/vue.md

@@ -0,0 +1,131 @@
+# Vue 规范适配器
+
+仅对 Project Inventory 明确识别为 Vue 的 scope 生成。Vue 2、Vue 3、Options API、Composition API、Nuxt 和纯 Vite Vue 的可用 API 不同，必须先识别版本和项目主导实践。
+
+Vue 官方 Style Guide 当前标注为需要更新，示例主要基于 Options API，未完整覆盖现代 Composition API 与 `<script setup>`。因此规则来源优先级为：当前 Vue Guide、TypeScript Guide、Composables/Testing/Security/Performance Guide、`eslint-plugin-vue` 官方配置，再把 Style Guide Priority A/B 作为版本适用的默认建议，而不是唯一权威。
+
+## 版本与模式
+
+记录：
+
+- Vue 2 或 Vue 3 及精确大/小版本范围；
+- `vue-template-compiler`、`@vue/compiler-sfc`、compat build；
+- Options API、Composition API 或混合迁移；
+- `<script setup>`、普通 `setup()`、JSX/TSX；
+- Vite、Vue CLI、Nuxt 等构建模型；
+- Pinia、Vuex 或其他状态方案；
+- SSR/SSG、hydration 和客户端专属边界。
+
+默认策略：Vue 3 新模块或仓库已占主导时 SHOULD 使用 Composition API 与 `<script setup lang="ts">`；Vue 2 或稳定 Options API 存量模块保持局部一致，通过 Ratchet 迁移，绝不生成不可用 API。
+
+## SFC 与组件边界
+
+- 一个 SFC 表达一个主要组件；小型局部辅助渲染逻辑可按项目实践保留。
+- 文件、组件 `name`、模板标签和自动导入约定保持可追踪；无冲突的新项目默认多词业务组件名，根组件和框架特殊文件可例外。
+- props、emits、slots 和 model 是公开合同；父传子、子发事件，组件不得修改 prop 或其不拥有的对象。
+- UI、领域规则、请求编排和平台副作用在复杂度出现时分离；不按机械行数拆成无意义 composable。
+
+## TypeScript 组件合同
+
+Vue 3 `<script setup>` 按项目版本使用类型化宏：
+
+- `defineProps`：运行时声明和纯类型声明二选一，不混用；外部输入仍需要运行时验证时显式提供 validator/schema。
+- props 默认值使用当前版本支持的 reactive destructure 或 `withDefaults`；生成规则必须匹配项目 Vue/compiler 版本。
+- `defineEmits`：事件名和 payload 精确类型化；不以无约束字符串事件替代合同。
+- `defineSlots`、template refs、`provide/inject` 与 `InjectionKey` 在项目版本支持时建立类型安全。
+- `defineModel` 仅在项目 Vue 版本和约定支持时使用；否则使用明确 `modelValue` / `update:modelValue` 合同。
+- 不用 `as any` 或非空断言隐藏 mount 前 template ref 为空、可选注入或异步数据状态。
+
+Options API 模块使用 `defineComponent`、`PropType` 和项目当前推断方式；不为了使用新语法重写稳定组件。
+
+## 响应式状态
+
+- `ref` 用于独立值和需要可替换引用的状态；`reactive` 用于稳定对象图；遵循当前 Vue 版本的解构语义。
+- 派生数据使用纯 `computed`，不复制到可变 ref，也不在 computed getter 中写状态或执行 I/O。
+- 模板和脚本中的 ref 解包差异必须被理解；不得依赖偶然自动解包。
+- 外部不可深代理对象、超大不可变结构或第三方实例按需要使用 `shallowRef`、`markRaw` 等，并记录边界理由。
+- state 的所有者明确；局部状态不因“可能复用”提前提升到全局 store。
+
+## watch、watchEffect 与生命周期
+
+- `watch` 用于明确源、需要前后值或精确触发控制的副作用；`watchEffect` 用于依赖可由同步执行自然收集的副作用。
+- 可由 `computed` 或事件直接完成的逻辑不使用 watcher。
+- watcher、timer、DOM listener、subscription、observer 和请求必须清理；使用当前版本支持的 cleanup API，并覆盖过期异步结果。
+- 明确 flush timing；依赖更新后 DOM 的逻辑使用适合的 post-flush 或 `nextTick`，不靠任意 timeout。
+- 只能在组件实例存在时运行的副作用放在正确生命周期；SSR 中不在服务端执行浏览器专属 API。
+
+## Composable
+
+- 复用有状态逻辑的函数使用 `useXxx`；工厂/纯函数不滥用 `use` 前缀。
+- 需要生命周期注入的 composable 在 `setup()` / `<script setup>` 同步调用，并文档化调用上下文。
+- 输入可变化时接受 ref/getter/MaybeRefOrGetter，并在 reactive effect 中规范化；不要在调用时一次性读取后失去响应性。
+- 默认返回包含 refs 的普通对象，以便解构后保持响应性；返回 reactive object 时明确解构限制。
+- composable 拥有的资源在 scope dispose/unmount 时释放；全局单例资源需有独立生命周期与测试重置机制。
+- composable 不隐藏跨模块写入、路由跳转或 toast 等副作用，除非名称和合同明确。
+
+## 组件通信与状态管理
+
+- props down / events up；跨层共享服务使用明确 provide/inject contract，避免字符串 key 冲突。
+- slots/scoped slots 的 slot props 是公开合同；默认内容和必需 slot 行为可测试。
+- Pinia/Vuex 只在项目已采用或用户确认时生成专属规则。Pinia store：state 可序列化边界明确，getter 保持派生，action 表达业务操作，SSR 时隔离请求状态。
+- 不把所有请求缓存、表单草稿和瞬时 UI 状态集中进全局 store。
+
+## Template、可访问性与安全
+
+- `v-for` 使用稳定业务 key，不用会变化的 index 代表可重排实体。
+- 避免在同一元素组合 `v-if` 与 `v-for`；先过滤/计算集合或提升条件。
+- `v-if` 用于真实挂载切换，`v-show` 用于高频可见性切换；按成本选择。
+- 事件 modifier、attribute fallthrough 和多根组件行为按组件 contract 使用，不依赖隐式透传。
+- 优先语义 HTML、label、键盘交互、焦点管理和可访问名称。
+- `v-html` 只接受经过可信边界消毒或完全受信任的内容；用户模板、URL、style 和脚本均视为安全边界。
+
+## SSR、hydration 与性能
+
+- 服务端 render 必须确定；随机数、时间、浏览器状态和全局单例按请求隔离或在 hydration 后处理。
+- DOM、window、storage、observer 和 browser-only 库放在客户端生命周期/guard 中。
+- 先稳定 props、缩小响应式依赖和组件边界；测量后再采用 shallow API、`v-memo`、虚拟列表或手工缓存。
+- 大组件/路由按现有 bundler 使用异步组件和 code splitting；不因拆包破坏错误与加载状态。
+
+## 测试
+
+- 使用项目既有 Vue Test Utils、Vitest/Jest、Testing Library、Playwright/Cypress 等工具。
+- 组件测试断言公开 DOM、emits、slot、可访问交互和用户行为；不依赖 `wrapper.vm` 私有实现作为主要合同。
+- snapshot 只能补充稳定结构，不替代行为断言。
+- composable 的纯逻辑可直接测试；依赖生命周期/provide/inject 的 composable 通过最小宿主组件测试并验证 cleanup。
+- 与 CSS layout、原生浏览器事件、focus、teleport、hydration 或平台 API 强相关的行为使用 browser component/E2E。
+- store 测试隔离 active Pinia/全局状态，覆盖 action 失败、并发和 SSR 污染风险。
+
+## 工具链
+
+- ESLint 使用项目版本匹配的 `eslint-plugin-vue` flat/legacy config，至少覆盖对应 Vue 版本的 essential correctness rules；recommended/style 层按项目选择。
+- TypeScript SFC 使用项目当前认可的 parser、language tools 和 `vue-tsc`/framework typecheck；编辑器通过不等于 CI typecheck。
+- formatter 与 template/style block 一致；避免 ESLint 与 formatter 争夺机械格式。
+- 自动导入、宏和类型生成文件必须由 CI 验证 freshness，并从手写规则中排除。
+
+## 访谈触发
+
+仅在证据冲突时询问：
+
+- Vue 2/compat → Vue 3 的目标与期限；
+- Options API、Composition API、`<script setup>` 的新增代码策略；
+- Pinia/Vuex 迁移与局部/全局状态边界；
+- `defineModel`、reactive props destructure 等版本相关能力；
+- unit/component/browser/E2E 的责任边界；
+- Nuxt server/client 与 SSR 状态隔离。
+
+## 输出验收
+
+Vue scope 的生成规范必须同时覆盖：组件合同、响应式、composable、watch/cleanup、模板安全与可访问性、SSR（如适用）、测试和实际工具链。不得只生成文件命名和 `<script setup>` 偏好。
+
+## 官方依据
+
+- [Vue TypeScript with Composition API](https://vuejs.org/guide/typescript/composition-api.html)
+- [Vue Composables](https://vuejs.org/guide/reusability/composables.html)
+- [Vue Watchers](https://vuejs.org/guide/essentials/watchers.html)
+- [Vue Testing](https://vuejs.org/guide/scaling-up/testing.html)
+- [Vue Security](https://vuejs.org/guide/best-practices/security.html)
+- [Vue Performance](https://vuejs.org/guide/best-practices/performance.html)
+- [Vue Accessibility](https://vuejs.org/guide/best-practices/accessibility.html)
+- [Vue Style Guide status](https://vuejs.org/style-guide/)
+- [eslint-plugin-vue user guide](https://eslint.vuejs.org/user-guide/)
+- [Pinia core concepts](https://pinia.vuejs.org/core-concepts/)

package/template/skills/engineering-standards-builder/references/typescript/runtimes/browser.md

@@ -0,0 +1,15 @@
+# Browser 运行时
+
+仅用于明确运行在浏览器、Web Worker 或 Service Worker 的 TypeScript/JavaScript scope。
+
+- DOM 查询和操作局限在 UI/platform adapter；框架模块遵循框架生命周期。
+- 网络请求定义取消、超时、重试、认证刷新、离线和过期响应语义。
+- storage、cookie、URL、postMessage 和第三方脚本属于不可信边界。
+- 不在 bundle 中暴露 secret；构建时变量凡进入客户端均视为公开。
+- 事件监听、observer、object URL、worker 和 timer 有清理路径。
+- 用户输入、富文本和 URL 按上下文验证/转义；CSP、Trusted Types 等只在项目采用时生成。
+- 性能以用户指标和 bundle/runtime 测量为依据；大列表虚拟化、图片和 code splitting 按证据采用。
+- 可访问性、键盘和焦点纳入组件与 E2E 门禁。
+- Worker 与 window 使用独立 tsconfig/lib，消息通过类型化且运行时验证的协议。
+
+官方依据：[MDN Web APIs](https://developer.mozilla.org/docs/Web/API)、[OWASP Cheat Sheet Series](https://cheatsheetseries.owasp.org/)。

package/template/skills/engineering-standards-builder/references/typescript/runtimes/electron.md

@@ -0,0 +1,25 @@
+# Electron 运行时
+
+仅在依赖、入口和构建配置明确识别 Electron 时使用。
+
+## 进程边界
+
+- main、preload、renderer 使用独立入口和类型/构建环境；renderer 不继承 Node 权限。
+- 默认保持 `contextIsolation`，关闭不必要的 `nodeIntegration`；安全配置以项目 Electron 版本官方建议为准。
+- preload 只暴露最小、具名、类型化 API；不直接暴露 `ipcRenderer`、fs 或任意执行能力。
+- IPC channel 是 public security contract：验证 sender、channel、payload、权限和响应；不信任 renderer 输入。
+- BrowserWindow、tray、session、shortcut、listener 和 child process 有唯一所有者和销毁路径。
+
+## 数据与更新
+
+- 文件路径、协议 handler、deep link、下载和外部 URL 均验证；外部导航使用 allowlist。
+- 自动更新、签名、安装权限和回滚按目标平台与发布系统生成，不编造通用命令。
+- main/renderer 共享 schema 或 generated types 时验证生成 freshness 和运行时数据。
+
+## 测试
+
+- 纯 IPC handler 和 domain logic 单元测试；
+- preload contract 与 main/renderer 集成测试；
+- 权限、窗口生命周期、安装包和平台差异使用实际 Electron/目标 OS 测试。
+
+官方依据：[Electron Security](https://www.electronjs.org/docs/latest/tutorial/security)、[Electron Context Isolation](https://www.electronjs.org/docs/latest/tutorial/context-isolation)。

package/template/skills/engineering-standards-builder/references/typescript/runtimes/node.md

@@ -0,0 +1,13 @@
+# Node.js 运行时
+
+- Node 版本来自 `engines`、版本文件、CI 或容器；可用 API 与 module 行为必须匹配该版本。
+- 配置在入口读取、验证、冻结并注入；库代码不随处访问 `process.env`。
+- 文件、socket、stream、child process、worker 和 timer 有错误、取消、关闭和进程退出策略。
+- stream 使用 backpressure，pipeline/finished 等结构化机制按项目版本选择。
+- process-level `uncaughtException` / `unhandledRejection` 只用于记录和受控终止，不假装安全恢复未知状态。
+- signal handling、graceful shutdown 和 exit code 属于应用入口合同。
+- 路径以明确根解析，拒绝遍历和 symlink 越界；跨平台处理分隔符、shell 和可执行文件。
+- 服务不得执行未验证 shell 字符串；优先参数化 spawn API。
+- package ESM/CJS、exports 和运行时加载行为通过实际 Node 测试。
+
+官方依据：[Node.js API documentation](https://nodejs.org/api/)、[Node.js package modules](https://nodejs.org/api/packages.html)。