@namewta/speculo 0.3.2 → 0.3.4

package/template/skills/typescript-engineering-standards/references/10-formatting-lint-and-complexity.md

@@ -0,0 +1,107 @@
+# 格式化、Lint 与复杂度
+
+## 工具统一风格
+
+格式由 Prettier、Oxfmt、Biome 或仓库选定工具自动完成。代码评审不讨论工具已能确定的空格、换行和引号偏好。
+
+常见基线：
+
+```json
+{
+  "singleQuote": true,
+  "semi": false,
+  "printWidth": 100,
+  "trailingComma": "none"
+}
+```
+
+具体值可不同，但必须全项目一致并在 CI 检查。
+
+## 通用格式规则
+
+- 2 空格缩进，除非仓库明确不同。
+- 文件使用 LF 和末尾换行。
+- 控制结构始终使用花括号。
+- 不手工用空格对齐列。
+- 避免将功能修改与全仓库格式化混在同一变更。
+- 生成文件由生成器维护，不人工格式化修改。
+
+## Lint 覆盖
+
+### 正确性
+
+- 未使用变量和导入。
+- 浮动 Promise。
+- 不可达代码、重复分支。
+- React Hooks 规则。
+- 意外赋值或错误比较。
+- 无效正则和转义。
+
+### TypeScript
+
+- 显式 `any`。
+- 类型导入一致性。
+- 无意义断言。
+- Switch 穷尽检查。
+- `@ts-ignore`。
+- 不安全成员访问和调用；在性能允许时启用类型感知规则。
+
+### 架构与维护
+
+- 循环依赖。
+- 禁止跨层导入。
+- 文件大小。
+- 函数复杂度和嵌套。
+- 重复导入。
+- 无意义 Barrel。
+
+## 禁用规则
+
+禁用必须：
+
+- 精确到单行或最小块。
+- 指明规则名。
+- 说明无法通过设计消除的原因。
+- 有退出条件时附跟踪编号。
+
+```ts
+// eslint-disable-next-line no-await-in-loop -- Server requires ordered writes.
+await sendBatch(batch)
+```
+
+禁止文件级关闭核心类型安全、Hooks 或 Promise 规则来掩盖问题。
+
+## 文件大小预算
+
+建议触发审查的阈值：
+
+| 文件 | 软上限 |
+|---|---:|
+| 普通 `.ts` | 300 行 |
+| React `.tsx` | 400 行 |
+| 测试 | 600～800 行 |
+| 构建/生成脚本 | 600 行 |
+| 函数 | 40～60 行 |
+
+行数不是唯一指标。还应考虑：
+
+- 分支和圈复杂度。
+- 依赖数量。
+- 状态数量。
+- 修改频率。
+- 是否混合多个抽象层级。
+
+## 拆分方向
+
+- 解析与验证。
+- 领域规则与 I/O。
+- 状态定义与 Selector。
+- UI 容器与展示组件。
+- 平台无关逻辑与平台适配器。
+- 公共契约与内部实现。
+
+拆分后文件名必须具体，不得产生新的 `helpers.ts`。
+
+## 遗留文件
+
+对历史超限文件采用 Ratchet：不要求一次全部重写，但新修改不应继续扩大；每次触及时降低复杂度或提取一项明确职责。

package/template/skills/typescript-engineering-standards/references/11-configuration-dependencies-and-ci.md

@@ -0,0 +1,86 @@
+# 配置、依赖与 CI
+
+## TypeScript 配置
+
+- 不同运行环境使用独立配置或项目引用。
+- 共享基线放在 `tsconfig.base.json`。
+- 根配置只负责组合时可使用 `files: []` 和 `references`。
+- 浏览器和 Node 的 `lib`、`types`、模块解析应隔离。
+- 不通过放宽配置掩盖单个文件问题。
+
+## `package.json` 脚本
+
+提供稳定命令名，使开发者和 CI 不依赖具体工具：
+
+```json
+{
+  "scripts": {
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsc -b",
+    "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm test && pnpm build"
+  }
+}
+```
+
+实际工具可以替换，但脚本职责保持稳定。
+
+## 依赖分类
+
+- 运行时需要的包放 `dependencies`。
+- 构建、测试、类型和格式工具放 `devDependencies`。
+- 锁文件必须提交。
+- `packageManager` 固定包管理器及版本。
+- 新依赖评估维护状态、体积、许可证、安全和平台兼容性。
+- 不为一个简单函数引入大型依赖。
+- 同一能力避免并存多个库。
+
+## 配置边界
+
+配置在入口处解析并转换为只读、类型安全对象。区分：
+
+- 构建时配置。
+- 启动时环境配置。
+- 用户配置。
+- 动态远端配置。
+
+业务代码通过依赖或上下文接收配置，不到处读取全局变量。
+
+## CI 门禁
+
+推荐顺序：
+
+```text
+install
+  → format:check
+  → lint
+  → typecheck
+  → unit tests
+  → build
+  → integration/e2e
+```
+
+按项目增加：
+
+- 依赖边界检查。
+- 文件大小和复杂度检查。
+- 安全扫描。
+- 许可证检查。
+- 本地化键检查。
+- 包体积或性能预算。
+
+## 本地钩子
+
+提交前钩子可仅处理暂存文件，保证快速反馈；完整类型检查、测试和构建必须由 CI 执行。
+
+## 禁止的“通过”方式
+
+- 删除或长期跳过失败测试。
+- 关闭核心 Lint 规则。
+- 扩大 `any` 或强制断言。
+- 放宽 TypeScript 配置而无迁移计划。
+- 降低测试范围以隐藏回归。
+- 忽略构建警告或生成失败。

package/template/skills/typescript-engineering-standards/references/12-security-performance-and-i18n.md

@@ -0,0 +1,65 @@
+# 安全、性能与国际化
+
+## 输入安全
+
+所有外部输入必须验证，包括 API、IPC、消息、配置、文件、URL 和用户输入。
+
+- 路径防止目录穿越。
+- SQL 使用参数化查询。
+- Shell 使用参数数组并正确转义。
+- HTML 默认转义，谨慎使用原始 HTML。
+- URL、重定向和文件类型需要校验。
+- 跨窗口、跨进程消息校验来源和结构。
+
+## 敏感信息
+
+禁止：
+
+- 日志记录密码、Token、Cookie、私钥。
+- 将秘密打包到浏览器代码。
+- 提交 `.env`、证书或生产配置。
+- 向最终用户泄露内部堆栈、路径和未脱敏请求。
+- 把用户输入直接作为命令、查询或文件路径执行。
+
+日志应使用结构化字段并在边界脱敏。
+
+## 权限
+
+- 默认最小权限。
+- 权限判断集中在策略或 Guard 中。
+- UI 隐藏按钮不能替代服务端鉴权。
+- 高风险操作有确认、审计和幂等保护。
+- 不依赖客户端可篡改字段作最终安全决策。
+
+## 性能原则
+
+- 优化以前先测量。
+- 优先改进算法复杂度、I/O 次数和数据复制。
+- 大文件、日志和列表使用流式、分页、窗口化或虚拟化。
+- 避免热路径重复解析配置、创建正则、序列化大型对象或读取磁盘。
+- 定时器、监听器、队列和缓存必须有上限和清理。
+
+## 缓存
+
+缓存需要明确：
+
+- 键和命名空间。
+- 容量上限。
+- 淘汰策略。
+- 过期和主动失效。
+- 一致性要求。
+- 是否缓存错误或空结果。
+
+非直观优化应有基准、回归测试或简短原因说明。
+
+## 国际化
+
+有多语言需求时：
+
+- 用户可见文本不散落为硬编码字符串。
+- 文案键按领域语义命名，不按屏幕位置命名。
+- 插值使用具名参数。
+- 不拼接自然语言句子。
+- 日期、数字、货币和复数使用国际化 API。
+- 用户提示和开发日志分离。
+- CI 检查缺失键、未使用键和占位符不一致。

package/template/skills/typescript-engineering-standards/references/13-git-review-and-delivery.md

@@ -0,0 +1,79 @@
+# Git、代码评审与交付
+
+## 分支命名
+
+推荐：
+
+- `feat/workspace-search`
+- `fix/session-timeout-race`
+- `refactor/terminal-state-split`
+- `perf/large-log-rendering`
+- `test/payment-retry-policy`
+- `docs/typescript-style-guide`
+- `chore/upgrade-vitest`
+
+避免 `update`、`changes`、`fix-stuff` 等无语义名称。
+
+## 提交信息
+
+可采用 Conventional Commits：
+
+```text
+feat(auth): add device authorization flow
+fix(terminal): prevent duplicate process cleanup
+refactor(store): split workspace selectors
+test(cli): cover empty shell argument
+```
+
+提交应：
+
+- 聚焦一个逻辑变化。
+- 不混入无关格式化。
+- 能通过基本检查。
+- 不包含秘密、构建产物和本地配置。
+- 说明改变的目的，而不仅是文件列表。
+
+## Pull Request
+
+PR 应包含：
+
+- 背景和问题。
+- 方案和关键取舍。
+- 风险、兼容性和迁移影响。
+- 验证方式。
+- UI 变化的截图或录屏。
+- 缺陷修复的回归测试。
+- 未完成项和后续工作。
+
+## 审查优先级
+
+1. 正确性、安全、数据完整性。
+2. 类型边界和运行时验证。
+3. 资源生命周期、并发、错误处理。
+4. 架构边界和公共 API。
+5. 测试缺口。
+6. 可维护性与命名。
+7. 风格。
+
+## 审查意见格式
+
+一条有效意见应尽量说明：
+
+- 具体位置。
+- 真实风险。
+- 触发条件。
+- 建议修复方向。
+- 是否阻塞合并。
+
+不要只写“这里不好”“建议重构”。
+
+## 交付检查
+
+- 格式检查通过。
+- Lint 通过。
+- 类型检查通过。
+- 相关测试通过。
+- 构建通过。
+- 文档和配置同步。
+- 没有无关改动。
+- 已评估跨平台、安全、性能和兼容性。

package/template/skills/typescript-engineering-standards/references/14-adoption-exceptions-and-migration.md

@@ -0,0 +1,84 @@
+# 落地、例外与迁移
+
+## 例外原则
+
+规范允许例外，但不允许无记录的例外。例外必须：
+
+1. 有具体技术原因。
+2. 范围尽可能小。
+3. 在代码、配置或 PR 中说明。
+4. 不破坏核心安全与类型边界。
+5. 临时例外有退出条件和跟踪任务。
+6. 经代码评审确认。
+
+## 例外示例
+
+```ts
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+// Why: Vendor callback type is incorrect; remove after SDK-481 is fixed.
+function normalizeVendorPayload(payload: any): NormalizedPayload {
+  return vendorPayloadSchema.parse(payload)
+}
+```
+
+该例外仍在边界进行运行时验证，不让 `any` 传播。
+
+## 遗留项目迁移
+
+不要一次性重写全部代码。推荐阶段：
+
+### 阶段 1：建立事实和门禁
+
+- 固定包管理器和锁文件。
+- 增加稳定的 `format:check`、`lint`、`typecheck`、`test`、`build` 命令。
+- CI 先报告问题，再逐步改为阻塞。
+
+### 阶段 2：阻止新增债务
+
+- 新文件遵守命名和大小规则。
+- 新 API 不使用 `any`。
+- 新外部输入必须验证。
+- 新缺陷修复补回归测试。
+
+### 阶段 3：按触及范围治理
+
+- 修改旧文件时降低复杂度。
+- 拆出纯逻辑并补测试。
+- 清理循环依赖和万能工具文件。
+- 缩小公共 API。
+
+### 阶段 4：专项迁移
+
+- 分模块开启更严格的 TypeScript 选项。
+- 按领域迁移目录。
+- 引入项目引用和依赖边界检查。
+- 清理临时规则禁用和类型断言。
+
+## Ratchet 策略
+
+对无法立即达标的指标采用“只降不升”：
+
+- 文件行数不能继续增长。
+- `any` 数量不能增加。
+- 循环依赖数量不能增加。
+- 被跳过测试数量不能增加。
+- Lint 警告基线只能下降。
+
+## 自动生成代码
+
+生成代码可以豁免部分格式、大小和命名规则，但必须：
+
+- 明确标识生成来源。
+- 不手工修改。
+- 将生成目录排除在不适用检查外。
+- 对生成器本身进行测试和审查。
+
+## 大规模重命名
+
+只有在用户明确要求或迁移收益充分时进行。应：
+
+- 单独 PR。
+- 不混入功能变化。
+- 使用自动化重构工具。
+- 检查大小写敏感文件系统和 Git 重命名。
+- 验证导入、测试、文档和构建。

package/template/skills/typescript-engineering-standards/references/15-orca-derived-observations.md

@@ -0,0 +1,54 @@
+# 从 Orca 项目提炼的工程习惯
+
+本文件记录从 Orca 类型项目实践中抽象出的可迁移经验。它不是要求其他项目复制 Electron 目录，也不是 Orca 上游规范的逐字镜像。
+
+## 1. 运行环境边界优先
+
+Orca 一类 Electron 项目天然包含主进程、预加载、渲染器、共享代码和命令行等不同运行环境。可迁移经验是：
+
+- 运行能力不同的代码应物理隔离。
+- 每个环境使用适合自己的 TypeScript 配置和依赖范围。
+- 跨边界接口显式化，而不是随意互相导入。
+
+## 2. 领域内部局部平铺
+
+Orca 的工程习惯体现出：同一明确职责区域不必为每个实现再加一层目录。可迁移经验是：
+
+- 小型领域优先平铺。
+- 文件名承担定位职责。
+- 只有形成稳定子域后再增加目录。
+
+## 3. 文件名具体
+
+相较 `utils.ts`、`helpers.ts`，具体动作和领域名称更利于搜索、审查和拆分。例如清理、解析、引用、状态选择、平台适配等职责可以直接进入文件名。
+
+## 4. 控制文件体积
+
+对普通 TypeScript、React 文件和测试设置不同的大小预算，可以提前暴露职责混合。数字应视为审查触发器，而非机械规则。
+
+## 5. 注释关注 WHY
+
+简短解释兼容性、性能、安全和平台差异，比逐行描述实现更有价值。注释不能替代清晰命名和模块拆分。
+
+## 6. 工具链形成门禁
+
+Orca 类现代项目通常将格式化、Lint、类型检查、测试和 Git/CI 检查组合起来。可迁移经验是：
+
+- 规范应尽量机器可执行。
+- 命令名保持稳定，底层工具可替换。
+- 不允许通过关闭规则或删除测试绕过门禁。
+
+## 7. 测试靠近实现
+
+单元测试和实现共置，便于发现、移动和维护；集成和 E2E 测试则按跨模块边界集中管理。
+
+## 8. 不机械复制
+
+不应直接复制：
+
+- Electron 专属目录到普通 Node 或 Web 项目。
+- 某个具体格式工具的全部选项。
+- 某个仓库的行数阈值作为绝对标准。
+- 某个框架生成目录的特殊命名。
+
+应复制的是背后的目的：边界清晰、职责具体、类型严格、质量自动化、修改可验证。

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

@@ -0,0 +1,45 @@
+# Reference Index
+
+本目录保存 TypeScript 工程规范的详细知识模块。`SKILL.md` 是唯一主入口；执行具体任务时只读取必要模块。
+
+## 分类
+
+### 治理与决策
+
+- `00-standard-levels-and-precedence.md`：规则级别、冲突处理、事实优先。
+- `14-adoption-exceptions-and-migration.md`：例外、遗留项目、渐进迁移。
+- `15-orca-derived-observations.md`：从 Orca 工程实践中抽象出的可迁移经验。
+
+### 架构与代码组织
+
+- `01-project-architecture-and-directory-layout.md`
+- `02-file-directory-and-symbol-naming.md`
+- `03-modules-imports-exports-and-dependencies.md`
+
+### 语言与实现
+
+- `04-typescript-type-system.md`
+- `05-functions-async-errors-and-resources.md`
+- `06-comments-jsdoc-and-documentation.md`
+
+### 平台与测试
+
+- `07-testing-strategy.md`
+- `08-react-and-frontend.md`
+- `09-node-cli-and-cross-platform.md`
+
+### 工程化与交付
+
+- `10-formatting-lint-and-complexity.md`
+- `11-configuration-dependencies-and-ci.md`
+- `12-security-performance-and-i18n.md`
+- `13-git-review-and-delivery.md`
+
+## 读取原则
+
+- 单文件命名问题：读取 `02`，通常无需读取其他文件。
+- 类型错误或 API 设计：读取 `04`，涉及异步时再读 `05`。
+- 新领域目录设计：读取 `01`、`02`、`03`。
+- React 组件重构：读取 `08`，并按需补充 `04`、`05`、`07`。
+- 全仓库审计：从 `00` 开始，再按仓库技术栈选择相关模块。
+- 制定团队规范：先读 `00`、`01`、`02`、`04`、`10`、`11`、`13`，其余按技术栈补充。

package/template/skills/typescript-engineering-standards/templates/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

package/template/skills/typescript-engineering-standards/templates/AGENTS.typescript.md

@@ -0,0 +1,21 @@
+# TypeScript Project Rules
+
+- 先按运行环境和业务领域组织代码，领域内部优先局部平铺。
+- 目录与普通 TypeScript 文件使用 `kebab-case`；组件文件沿用项目统一规则。
+- 文件名必须表达具体领域和职责，避免 `utils`、`helpers`、`common`、`misc`。
+- 一个文件只有一个主要职责；不要为单个普通文件创建目录。
+- 默认使用命名导出；仅在框架约定入口使用默认导出。
+- 禁止无意义全局 Barrel 和循环依赖。
+- TypeScript 必须开启严格模式；禁止无说明的 `any`、双重断言和 `@ts-ignore`。
+- 外部输入先作为 `unknown`，在系统边界运行时验证。
+- 优先使用可辨识联合表达互斥状态，并进行穷尽检查。
+- 导出函数和公共 API 写明确返回类型。
+- 所有 Promise 必须 `await`、`return` 或显式处理。
+- 监听器、Timer、连接、Worker 和进程必须有清理路径。
+- 注释解释 WHY、约束和权衡，不逐行翻译代码。
+- 单元测试与源码共置；集成和 E2E 测试放在根级 `tests/`。
+- 修复缺陷时添加回归测试。
+- 不引入未经要求的新框架或依赖。
+- 不通过关闭核心规则、删除测试或扩大 `any` 来绕过检查。
+- 合并前运行格式检查、Lint、类型检查、测试和构建。
+- 修改现有项目时优先遵守仓库已生效配置，避免无关重命名和格式噪声。

package/template/skills/typescript-engineering-standards/templates/code-review-checklist.md

@@ -0,0 +1,37 @@
+# TypeScript Code Review Checklist
+
+## 正确性与安全
+
+- [ ] 外部输入已验证。
+- [ ] 权限、安全和敏感信息处理正确。
+- [ ] 错误路径不会造成数据损坏或状态不一致。
+
+## 类型与 API
+
+- [ ] 没有无说明的 `any`、双重断言或 `@ts-ignore`。
+- [ ] 公共 API 输入、输出和错误契约明确。
+- [ ] 互斥状态使用可靠模型，分支穷尽。
+- [ ] 空值和可选语义清晰。
+
+## 异步与资源
+
+- [ ] Promise 已等待、返回或显式处理。
+- [ ] 超时、取消和重试策略合理。
+- [ ] 监听器、Timer、连接和进程已清理。
+- [ ] 无明显竞态或过期响应覆盖问题。
+
+## 架构与维护
+
+- [ ] 文件位于正确领域和运行环境。
+- [ ] 文件名具体，职责单一。
+- [ ] 依赖方向正确，无循环依赖。
+- [ ] 没有无意义共享抽象和 Barrel。
+- [ ] 文件、函数和状态复杂度合理。
+
+## 测试与交付
+
+- [ ] 新行为有适当测试。
+- [ ] 缺陷修复有回归测试。
+- [ ] 测试确定、可诊断且不过度 Mock。
+- [ ] 格式、Lint、类型检查、测试和构建通过。
+- [ ] 无无关格式化、重命名或生成文件变化。

package/template/skills/typescript-engineering-standards/templates/package-scripts.json

@@ -0,0 +1,11 @@
+{
+  "scripts": {
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsc -b",
+    "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm test && pnpm build"
+  }
+}

package/template/skills/typescript-engineering-standards/templates/prettier.json

@@ -0,0 +1,6 @@
+{
+  "singleQuote": true,
+  "semi": false,
+  "printWidth": 100,
+  "trailingComma": "none"
+}

package/template/skills/typescript-engineering-standards/templates/pull-request-template.md

@@ -0,0 +1,37 @@
+## 背景
+
+<!-- 这个变更解决什么问题？ -->
+
+## 方案
+
+<!-- 核心实现、边界和主要取舍。 -->
+
+## 影响范围
+
+- [ ] 公共 API
+- [ ] 数据或配置迁移
+- [ ] 跨平台行为
+- [ ] 安全或权限
+- [ ] 性能
+- [ ] UI / 可访问性
+
+## 验证
+
+- [ ] 格式检查
+- [ ] Lint
+- [ ] TypeScript 类型检查
+- [ ] 单元测试
+- [ ] 集成 / E2E 测试
+- [ ] 构建
+
+## 证据
+
+<!-- 截图、录屏、日志、基准或测试结果。 -->
+
+## 风险与回滚
+
+<!-- 已知风险、兼容性和回滚方式。 -->
+
+## 后续工作
+
+<!-- 不属于本 PR 的工作，附任务编号。 -->

package/template/skills/typescript-engineering-standards/templates/tsconfig.base.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ES2022",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "useUnknownInCatchVariables": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  }
+}

package/template/skills/typescript-engineering-standards/templates/tsconfig.project-references.json

@@ -0,0 +1,8 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.node.json" },
+    { "path": "./tsconfig.web.json" },
+    { "path": "./tsconfig.test.json" }
+  ]
+}