@namewta/speculo 0.3.3 → 0.3.4

package/template/skills/typescript-engineering-standards/references/08-react-and-frontend.md

@@ -0,0 +1,91 @@
+# React 与前端规范
+
+## 组件职责
+
+组件输入由 Props 明确表达，渲染尽量纯粹。复杂功能按需拆分：
+
+- 数据获取与缓存。
+- 业务状态编排。
+- 领域交互。
+- 视觉展示。
+
+组件名称使用具体领域语义：
+
+- `WorkspaceReconnectDialog`
+- `TerminalPermissionBanner`
+- `PaymentMethodPanel`
+
+避免 `DataComponent`、`CommonModal`、`GenericPanel`。
+
+## Props
+
+```ts
+type WorkspaceCardProps = {
+  workspace: WorkspaceSummary
+  isSelected: boolean
+  onSelect(workspaceId: string): void
+}
+```
+
+要求：
+
+- 使用 `XxxProps`。
+- 布尔 Props 使用 `is`、`has`、`can`、`should`。
+- 事件 Props 使用 `onXxx`。
+- 避免大型万能对象和多个隐式控制模式的布尔值。
+- 复杂互斥状态使用联合类型。
+- 是否使用 `React.FC` 按仓库统一规则，不混用。
+
+## Hook
+
+- 自定义 Hook 以 `use` 开头。
+- 一个 Hook 处理一个可命名职责。
+- Effect 依赖完整，不通过关闭规则规避。
+- Effect 创建资源时返回清理函数。
+- 返回多个独立值时优先具名对象；稳定二元关系可用元组。
+- 避免把普通纯函数包装成 Hook。
+
+## 状态管理
+
+- 状态尽量靠近使用位置。
+- 只有多个远距离调用方共享时才提升。
+- Store 按领域切片，不创建单一巨型 Store。
+- Selector 尽量窄，避免组件订阅整个状态树。
+- 派生数据优先计算，不重复存储。
+- 服务端状态与本地 UI 状态分开管理。
+
+## Effect
+
+Effect 用于与外部系统同步，不用于替代普通计算。检查：
+
+- 是否可在渲染时直接派生。
+- 是否需要取消旧请求。
+- 是否存在竞态和过期响应。
+- 是否清理监听器、Timer 和订阅。
+- 是否因对象引用变化导致无意义重复执行。
+
+## 性能
+
+- 不因为“可能更快”滥用 `memo`、`useMemo`、`useCallback`。
+- 优化针对已识别瓶颈。
+- 长列表使用虚拟化。
+- 高频事件使用调度、批处理、节流或防抖。
+- 避免在热渲染路径创建昂贵对象。
+- 关键优化应有测试、测量或简短原因说明。
+
+## 可访问性
+
+- 优先语义化 HTML。
+- 交互元素支持键盘。
+- 图标按钮有可访问名称。
+- 表单控件有 Label 和错误关联。
+- 焦点管理可预测。
+- 不用颜色作为唯一状态表达。
+- 弹窗、菜单和提示遵守相应 ARIA 交互模式。
+
+## 浏览器边界
+
+- 验证 URL、消息、Storage 和第三方脚本输入。
+- 避免不安全原始 HTML。
+- 不把秘密放入前端 Bundle。
+- 浏览器代码不导入 Node 专属模块，除非平台明确提供安全桥接。

package/template/skills/typescript-engineering-standards/references/09-node-cli-and-cross-platform.md

@@ -0,0 +1,92 @@
+# Node.js、CLI 与跨平台规范
+
+## Node 内置模块
+
+使用 `node:` 前缀：
+
+```ts
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+```
+
+## 路径
+
+使用 `node:path` 组合和归一化路径，不手工拼接分隔符：
+
+```ts
+const configPath = path.join(rootPath, 'config', 'app.json')
+```
+
+涉及安全或相等判断时考虑：
+
+- Windows 盘符和分隔符。
+- UNC 路径。
+- 大小写敏感差异。
+- 符号链接。
+- 相对路径和路径遍历。
+- 规范化前后的边界检查顺序。
+
+## CLI 分层
+
+推荐拆分：
+
+- `parse-cli-arguments.ts`
+- `validate-cli-options.ts`
+- `run-export-command.ts`
+- `render-cli-error.ts`
+
+要求：
+
+- 参数解析与业务执行分离。
+- 正常机器输出写 `stdout`，错误写 `stderr`。
+- 明确定义退出码。
+- 支持 `--help` 和 `--version`。
+- 底层领域代码不直接调用 `process.exit()`。
+- 信号处理和资源清理集中管理。
+
+## 环境变量
+
+在启动边界一次解析、验证和标准化：
+
+```ts
+type AppEnvironment = {
+  port: number
+  logLevel: LogLevel
+}
+
+export function loadEnvironment(
+  source: NodeJS.ProcessEnv
+): AppEnvironment {
+  // ...
+}
+```
+
+业务代码不应在各处直接读取 `process.env`。
+
+## 子进程
+
+- 优先使用参数数组，不拼接 Shell 字符串。
+- 必须拼接时按目标 Shell 正确转义。
+- 处理超时、取消、退出码、信号和输出上限。
+- 避免将不可信输入直接作为命令或参数。
+- 明确清理孤儿进程。
+
+## 文件和流
+
+- 大文件优先流式处理。
+- 关闭文件句柄和流。
+- 处理背压。
+- 临时文件使用隔离目录并在失败路径清理。
+- 写关键文件时考虑原子替换和崩溃恢复。
+
+## 跨平台
+
+跨平台逻辑应集中在适配器中。测试至少覆盖：
+
+- 路径和换行符。
+- Shell 参数引用。
+- 文件权限和可执行位。
+- 信号差异。
+- 大小写和文件锁行为。
+
+不要把平台判断散落在整个业务代码中。

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`，其余按技术栈补充。