@namewta/speculo 0.3.2 → 0.3.4

package/template/skills/typescript-engineering-standards/examples/project-layouts.md

@@ -0,0 +1,75 @@
+# 项目目录示例
+
+## 小型 Node 服务
+
+```text
+src/
+├── app/
+│   ├── create-server.ts
+│   └── load-environment.ts
+├── features/
+│   └── user-auth/
+│       ├── authenticate-user.ts
+│       ├── authenticate-user.test.ts
+│       └── user-token.ts
+├── infrastructure/
+│   ├── database/
+│   └── http/
+└── shared/
+    └── result.ts
+```
+
+## React 应用
+
+```text
+src/
+├── app/
+│   ├── App.tsx
+│   └── routes.tsx
+├── features/
+│   ├── workspace-search/
+│   │   ├── WorkspaceSearchPanel.tsx
+│   │   ├── workspace-search-query.ts
+│   │   └── use-workspace-search.ts
+│   └── user-settings/
+├── shared/
+│   ├── components/
+│   └── hooks/
+└── infrastructure/
+    └── api/
+```
+
+`shared/components` 只放真正无业务归属且有多个真实调用方的组件。
+
+## Electron
+
+```text
+src/
+├── main/
+│   ├── app-lifecycle.ts
+│   └── windows/
+├── preload/
+│   └── workspace-api.ts
+├── renderer/
+│   ├── app/
+│   └── features/
+├── shared/
+│   └── workspace-contract.ts
+└── types/
+    └── electron-api.d.ts
+```
+
+## Monorepo
+
+```text
+apps/
+├── web/
+└── api/
+packages/
+├── domain/
+├── contracts/
+├── ui/
+└── test-support/
+```
+
+包边界应与独立发布、运行环境或稳定依赖方向对应，不要仅为缩短相对路径拆包。

package/template/skills/typescript-engineering-standards/examples/review-output-example.md

@@ -0,0 +1,25 @@
+# 代码审查输出示例
+
+## 阻塞问题
+
+### `src/features/workspace/load-workspace.ts:42`
+
+`JSON.parse()` 的结果被直接断言为 `WorkspaceConfig`。当配置缺少 `rootPath` 时，错误会延迟到文件系统调用，并可能访问错误位置。
+
+建议在配置边界使用 Schema 验证，将解析函数返回类型固定为已验证的 `WorkspaceConfig`，并补充缺失字段和路径穿越测试。
+
+## 重要问题
+
+### `src/main/process-registry.ts:88`
+
+关闭窗口时只移除了事件监听器，没有终止仍在运行的子进程。重复打开窗口会留下孤儿进程。
+
+建议让注册函数返回统一 `dispose()`，在窗口关闭和应用退出两个路径都调用，并增加清理回归测试。
+
+## 建议
+
+### `src/features/search/utils.ts`
+
+该文件同时包含查询解析、排序和本地存储。当前功能仍正确，但后续修改会持续扩大职责。
+
+建议在下一次触及该模块时拆为 `search-query-parser.ts`、`search-result-sort.ts` 和 `search-history-storage.ts`。本问题不必阻塞当前仅修复文案的变更。

package/template/skills/typescript-engineering-standards/examples/type-modeling-patterns.md

@@ -0,0 +1,66 @@
+# 类型建模示例
+
+## 状态机
+
+不推荐：
+
+```ts
+type RequestState = {
+  isLoading: boolean
+  hasError: boolean
+  data?: Data
+  error?: Error
+}
+```
+
+推荐：
+
+```ts
+type RequestState =
+  | { kind: 'idle' }
+  | { kind: 'loading' }
+  | { kind: 'success'; data: Data }
+  | { kind: 'failure'; error: Error }
+```
+
+## 外部边界
+
+```ts
+export function parseWorkspaceMessage(input: unknown): WorkspaceMessage {
+  return workspaceMessageSchema.parse(input)
+}
+```
+
+内部代码只接收已经验证的 `WorkspaceMessage`。
+
+## `satisfies`
+
+```ts
+const routes = {
+  home: '/',
+  settings: '/settings'
+} satisfies Record<string, `/${string}`>
+```
+
+保留具体字面量，同时验证整体契约。
+
+## 结果类型
+
+```ts
+type Result<TValue, TError> =
+  | { ok: true; value: TValue }
+  | { ok: false; error: TError }
+```
+
+适合调用方需要显式分支、失败属于正常业务结果的场景。不可恢复的程序错误仍可抛异常。
+
+## 单位类型
+
+高风险领域可使用品牌类型避免单位混用：
+
+```ts
+type Milliseconds = number & { readonly __brand: 'Milliseconds' }
+type Bytes = number & { readonly __brand: 'Bytes' }
+```
+
+仅在实际能降低错误且不会制造大量转换噪声时采用。

package/template/skills/typescript-engineering-standards/manifest.txt

@@ -0,0 +1,33 @@
+README.md
+SKILL.md
+examples/comment-patterns.md
+examples/naming-patterns.md
+examples/project-layouts.md
+examples/review-output-example.md
+examples/type-modeling-patterns.md
+references/00-standard-levels-and-precedence.md
+references/01-project-architecture-and-directory-layout.md
+references/02-file-directory-and-symbol-naming.md
+references/03-modules-imports-exports-and-dependencies.md
+references/04-typescript-type-system.md
+references/05-functions-async-errors-and-resources.md
+references/06-comments-jsdoc-and-documentation.md
+references/07-testing-strategy.md
+references/08-react-and-frontend.md
+references/09-node-cli-and-cross-platform.md
+references/10-formatting-lint-and-complexity.md
+references/11-configuration-dependencies-and-ci.md
+references/12-security-performance-and-i18n.md
+references/13-git-review-and-delivery.md
+references/14-adoption-exceptions-and-migration.md
+references/15-orca-derived-observations.md
+references/README.md
+templates/.editorconfig
+templates/AGENTS.typescript.md
+templates/code-review-checklist.md
+templates/package-scripts.json
+templates/prettier.json
+templates/pull-request-template.md
+templates/tsconfig.base.json
+templates/tsconfig.project-references.json
+manifest.txt

package/template/skills/typescript-engineering-standards/references/00-standard-levels-and-precedence.md

@@ -0,0 +1,51 @@
+# 规则级别与优先顺序
+
+## 规范词义
+
+- **必须**：影响正确性、安全、类型边界、资源生命周期或团队一致性的硬性要求。
+- **应当**：绝大多数情况下适用；偏离时应有可说明的理由。
+- **建议**：默认推荐，但可根据规模、框架和团队经验调整。
+- **禁止**：高概率制造缺陷、隐藏风险或显著降低维护性的做法。
+
+## 冲突优先级
+
+从高到低：
+
+1. 用户明确要求和产品约束。
+2. 运行平台、框架、协议或公开 API 的硬约束。
+3. 已生效的仓库配置与自动化检查。
+4. 当前模块一致、可解释的局部惯例。
+5. 本 Skill 的默认规范。
+
+## 事实优先
+
+审查现有项目时，不要仅凭文件名或技术栈推断规则。应读取配置和相邻实现，确认：
+
+- 模块系统是 ESM、CommonJS 还是打包器模式。
+- 测试框架和测试命名。
+- 格式化与 Lint 工具。
+- 路径别名和包边界。
+- React、Node、Electron 等运行环境。
+- 哪些文件由代码生成器维护。
+
+## 一致性不是绝对理由
+
+“项目一直这么写”不能自动证明做法正确。以下问题即使历史代码广泛存在，也应阻止继续扩散：
+
+- 不可信输入未经验证。
+- 敏感信息泄露。
+- 无法清理的监听器、Timer、连接或进程。
+- `any` 向公共 API 传播。
+- 循环依赖或跨运行环境非法导入。
+- 测试被删除、跳过或规则被关闭以掩盖失败。
+
+处理方式应以增量治理为主：新代码不继续引入，触及旧代码时适度修复，避免无关全仓库改写。
+
+## 建议与缺陷的区分
+
+代码审查中：
+
+- 能导致错误、安全问题或维护阻塞的，标记为缺陷。
+- 存在合理替代方案、但当前实现仍正确的，标记为建议。
+- 纯偏好且仓库已有统一风格的，不应提出。
+- 无法证明风险的猜测，应明确说明不确定性。

package/template/skills/typescript-engineering-standards/references/01-project-architecture-and-directory-layout.md

@@ -0,0 +1,105 @@
+# 项目架构与目录布局
+
+## 先表达边界
+
+目录优先表达以下稳定边界之一：
+
+- 运行环境：`main/`、`renderer/`、`server/`、`worker/`、`cli/`。
+- 产品领域：`user-auth/`、`orders/`、`payments/`。
+- 架构职责：`domain/`、`application/`、`infrastructure/`。
+- 独立发布单元：`apps/`、`packages/`。
+
+不要在同一层混合互不相干的分类逻辑，例如同时出现全局 `components/`、`payments/`、`services/`、`cli/`。
+
+## 领域优先，技术类型局部化
+
+项目很小时可按技术类型组织；业务增长后应将技术目录移动到领域内部。
+
+推荐：
+
+```text
+src/
+├── app/
+├── features/
+│   ├── user-auth/
+│   │   ├── login-service.ts
+│   │   ├── login-service.test.ts
+│   │   └── components/
+│   └── payments/
+├── shared/
+└── infrastructure/
+```
+
+不推荐长期维持：
+
+```text
+src/
+├── components/
+├── hooks/
+├── services/
+├── types/
+└── utils/
+```
+
+## 局部平铺
+
+一个职责明确的领域目录应默认平铺文件，不为每个文件建立同名目录。
+
+建议增加子目录的条件：
+
+- 形成稳定、可命名的子领域。
+- 同级实现文件长期超过约 8～12 个，定位成本明显上升。
+- 文件组拥有独立入口、资源、测试夹具或生命周期。
+- 文件组需要整体移动、替换或发布。
+- 依赖方向或运行环境需要物理隔离。
+
+不要创建仅包含一个普通实现文件的目录，也不要为了对称而制造空层级。
+
+## `shared/` 准入
+
+代码进入共享层前应满足：
+
+1. 至少有两个真实调用方。
+2. 不依赖具体业务领域。
+3. 具有具体、可命名的能力。
+4. API 相对稳定。
+5. 不会造成反向依赖。
+6. 共享确实减少重复，而非提前抽象。
+
+`shared/` 不是“不知道放哪里”的收容区。
+
+## 多运行环境
+
+Electron、全栈、Worker 或混合运行环境项目应物理隔离：
+
+```text
+src/
+├── main/
+├── preload/
+├── renderer/
+├── shared/
+└── types/
+```
+
+要求：
+
+- 各环境使用独立 `tsconfig` 或项目引用。
+- 浏览器代码不导入 Node 专属模块。
+- 服务端代码不无意依赖 DOM。
+- 跨环境数据通过显式、可序列化契约。
+- 桥接层 API 最小化，并验证来自外部边界的数据。
+
+## 推荐深度
+
+目录深度不是硬性指标，但从领域根目录到普通实现文件通常不应超过三层。深层目录往往表示过度分类、缺少领域命名或每文件一目录。
+
+## 拆分信号
+
+出现以下情况时考虑拆模块或拆包：
+
+- 一个目录同时包含多个运行环境代码。
+- 改动一个领域经常触发另一个无关领域。
+- 同一目录的文件命名需要大量前缀才能区分。
+- 公共入口不断扩大。
+- 依赖图出现循环。
+- 不同部分需要不同构建、发布或权限策略。

package/template/skills/typescript-engineering-standards/references/02-file-directory-and-symbol-naming.md

@@ -0,0 +1,117 @@
+# 文件、目录与标识符命名
+
+## 默认命名
+
+| 对象 | 默认规则 | 示例 |
+|---|---|---|
+| 目录 | `kebab-case` | `user-auth/` |
+| 普通 TypeScript 文件 | `kebab-case.ts` | `session-expiration-policy.ts` |
+| React 业务组件 | `PascalCase.tsx` | `SessionExpiredDialog.tsx` |
+| Hook | `use-*.ts` / `use-*.tsx` | `use-session-timeout.ts` |
+| 单元测试 | 源文件名 + `.test` | `login-service.test.ts` |
+| 集成测试 | `.integration.test` | `payment-flow.integration.test.ts` |
+| E2E | `.e2e.spec` | `checkout.e2e.spec.ts` |
+| 声明文件 | 环境或能力名 | `electron-api.d.ts` |
+| 工程脚本 | 动宾结构 | `generate-icons.ts` |
+
+若仓库已统一使用 `kebab-case.tsx` 组件文件，应保持一致。不要在同一领域混用两种组件文件命名。
+
+## 文件名表达领域和职责
+
+推荐结构：
+
+```text
+<domain>-<responsibility>.ts
+```
+
+例如：
+
+- `user-session-store.ts`
+- `payment-retry-policy.ts`
+- `terminal-output-parser.ts`
+- `github-auth-client.ts`
+- `workspace-path-validator.ts`
+
+## 职责后缀
+
+- `-service`：完成一个应用能力；不得成为万能类。
+- `-repository`：领域对象的持久化抽象。
+- `-client`：调用外部 HTTP、RPC 或 SDK。
+- `-adapter`：在两个接口或模型间适配。
+- `-gateway`：外部系统或资源边界。
+- `-store`：状态存储与更新。
+- `-selector`：从状态中派生数据。
+- `-policy`：可替换的业务决策。
+- `-validator`：校验并返回结果或错误。
+- `-parser`：把外部格式转换为结构化数据。
+- `-serializer`：把结构化数据转换为外部格式。
+- `-mapper`：在两个明确模型之间映射。
+- `-factory`：构造复杂对象或依赖图。
+- `-registry`：注册和查找一组实现。
+- `-scheduler`：计划或调度任务。
+- `-coordinator`：协调多个独立流程。
+- `-contract`：跨模块、跨进程或公开 API 契约。
+
+后缀不能替代领域信息。单独的 `service.ts`、`handler.ts`、`manager.ts` 仍然模糊。
+
+## 默认禁止的模糊名称
+
+- `utils.ts`
+- `helpers.ts`
+- `common.ts`
+- `misc.ts`
+- `general.ts`
+- `data.ts`
+- `manager.ts`
+- `processor.ts`
+- `handler.ts`
+- 全局 `types.ts`
+- 全局 `constants.ts`
+
+若父目录已提供完整语义，局部 `types.ts` 或 `constants.ts` 可以存在，但更推荐 `payment-types.ts`、`terminal-constants.ts` 等可搜索名称。
+
+## 标识符
+
+| 对象 | 规则 |
+|---|---|
+| 变量、函数、方法 | `camelCase` |
+| 类型、类、组件 | `PascalCase` |
+| 常量 | 真正全局稳定值用 `SCREAMING_SNAKE_CASE` |
+| 私有字段 | 使用 `#field` 或普通 `private`，不加 `_` 前缀 |
+| Hook | `useXxx` |
+| 事件属性 | `onXxx` |
+| 内部事件处理函数 | `handleXxx` |
+| 泛型 | 简单时 `T`，复杂时 `TResult`、`TContext` |
+
+## 布尔命名
+
+优先使用：
+
+- `isConnected`
+- `hasPendingChanges`
+- `canRetry`
+- `shouldPersist`
+- `didTimeout`
+- `willReconnect`
+
+避免 `flag`、`enabled`、`notDisabled`、`isNotInvalid` 等含义弱或双重否定名称。
+
+## 单位进入名称
+
+数值变量必须尽量包含单位或语义：
+
+```ts
+const timeoutMs = 30_000
+const payloadSizeBytes = 1_024
+const retryCount = 3
+const pageOffset = 20
+```
+
+## 避免无信息变量
+
+除极短循环或数学表达式外，避免 `obj`、`data`、`info`、`value`、`result`、`temp`。使用角色名称：
+
+- `parsedPayload`
+- `validationResult`
+- `pendingSession`
+- `persistedWorkspace`

package/template/skills/typescript-engineering-standards/references/03-modules-imports-exports-and-dependencies.md

@@ -0,0 +1,111 @@
+# 模块、导入、导出与依赖
+
+## 命名导出优先
+
+默认使用命名导出：
+
+```ts
+export function parseTerminalOutput(input: string): ParsedOutput {
+  // ...
+}
+```
+
+默认导出仅用于：
+
+- 框架规定的页面、路由或配置入口。
+- 工具链必须的默认导出。
+- 仓库已形成明确且一致的入口惯例。
+
+命名导出便于搜索、自动导入、重构和统一引用名称。
+
+## 一个文件一个主要公开概念
+
+一个文件可包含少量私有辅助函数，但通常只公开一个主要能力或一组高度相关能力。辅助函数达到独立职责后，应拆成具有具体名称的文件。
+
+不要为了测试内部细节而导出私有辅助函数；优先通过公共行为测试，或将真正独立的纯逻辑抽出。
+
+## Barrel 文件
+
+允许 `index.ts`：
+
+- 作为包或领域的明确公共入口。
+- 隐藏内部实现并稳定外部 API。
+- 作为依赖装配或框架入口。
+
+禁止：
+
+- 每个目录机械创建 `index.ts`。
+- 建立全项目万能 Barrel。
+- 通过 Barrel 暴露内部实现。
+- 通过 Barrel 形成循环依赖。
+
+## 导入顺序
+
+默认顺序：
+
+1. Node.js 内置模块。
+2. 第三方依赖。
+3. 项目别名。
+4. 相对路径实现。
+5. 类型导入按照工具规则分组或合并。
+
+```ts
+import { readFile } from 'node:fs/promises'
+
+import { z } from 'zod'
+
+import { createLogger } from '@/shared/logger'
+
+import { parseConfig } from './config-parser'
+
+import type { AppConfig } from './app-config'
+```
+
+要求：
+
+- Node 内置模块使用 `node:` 前缀。
+- 仅作为类型使用时采用 `import type`。
+- 不保留未使用或重复导入。
+- 副作用导入必须有明确原因。
+- 路径别名对应稳定边界，不用于任意跨层跳转。
+
+## 依赖方向
+
+推荐：
+
+```text
+UI / Entry
+    ↓
+Application orchestration
+    ↓
+Domain
+    ↓
+Ports / contracts
+    ↑
+Infrastructure adapters
+```
+
+- 领域逻辑不直接依赖数据库、HTTP、文件系统或 UI 框架。
+- 共享模块不依赖具体领域。
+- 底层模块不反向导入界面层。
+- 跨环境调用通过显式契约和适配器。
+
+## 循环依赖
+
+循环依赖是架构问题，不应通过调整导入顺序或增加 Barrel 隐藏。解决方式：
+
+- 提取真正共享的契约。
+- 使用依赖注入反转方向。
+- 合并实际属于同一职责的模块。
+- 将端口放在需求方而非实现方。
+- 缩小公共入口。
+
+## 公共 API
+
+公开库或跨包模块应：
+
+- 明确列出允许导出的入口。
+- 避免消费者导入内部路径。
+- 不暴露框架、数据库或第三方 SDK 的内部类型，除非这是刻意的 API 设计。
+- 保持输入、输出和错误契约稳定。
+- 变更时考虑语义化版本和迁移说明。