@namewta/speculo 0.3.4 → 0.4.0

package/template/skills/typescript-standards-builder/references/02-interview-workflow.md

@@ -0,0 +1,129 @@
+# 用户问答与决策收敛
+
+## 总体原则
+
+问答的目标是确认项目规则，而不是让用户重复描述仓库事实。
+
+- 一次确认一个决策维度。
+- 每个问题给出推荐默认值和理由。
+- 选项必须具体可执行，不使用“严格一点”“灵活一点”等空泛描述。
+- 用户回答后立即记录，不重复询问。
+- 只问真正影响生成结果的内容。
+- 固定默认原则不重复征求同意，除非存在硬冲突。
+
+## 推荐提问顺序
+
+### 1. 规范范围和遗留策略
+
+仅在范围不明确时询问：
+
+- 整个仓库。
+- 指定应用或包。
+- 新代码强制、旧代码 Ratchet。
+- 全量迁移并设置阶段计划。
+
+推荐：成熟项目采用“新代码强制、旧代码只降不升”。
+
+### 2. 目录主轴
+
+仅在仓库结构混乱或新项目中询问：
+
+- 业务领域优先，运行环境作为第一层边界。
+- 架构层优先。
+- 包边界优先的 Monorepo。
+- 保留现有结构，仅禁止继续扩散问题。
+
+默认：先隔离运行环境，再在环境内部按业务领域组织；领域内部局部平铺。
+
+### 3. React 文件命名
+
+仅 React 项目且仓库没有统一事实时询问：
+
+- `PascalCase.tsx` 业务组件，Hook 使用 `use-*.ts`。
+- 全部 `kebab-case.tsx`。
+- 保留生成器目录的特殊规则，业务代码使用统一规则。
+
+### 4. 模块和公开 API
+
+在导出方式不统一时询问：
+
+- 默认命名导出；默认导出仅限框架入口。
+- 保持现有默认导出惯例。
+- Barrel 仅允许作为领域或包公共入口。
+- 完全禁止 Barrel。
+
+推荐：命名导出优先，Barrel 只用于稳定公共入口。
+
+### 5. 类型建模
+
+在项目没有明确偏好时询问：
+
+- 默认 `type`，需要声明合并或扩展时使用 `interface`。
+- 默认 `interface`，联合和工具类型使用 `type`。
+- 完全遵循现有局部惯例。
+
+同时确认外部输入验证使用已有 Schema 库，还是要求自定义守卫。不得为此擅自引入新依赖。
+
+### 6. 文件大小预算
+
+根据实际分布推荐阈值。可询问：
+
+- 普通 `.ts`、`.tsx`、测试、脚本分别设置软上限。
+- 仅设置“超限必须说明”的审查门槛。
+- 先使用 Ratchet，不立即阻塞历史超限文件。
+
+推荐基线可从 `.ts` 300、`.tsx` 400、测试 700、脚本 600 行开始，但必须根据项目分位数调整。
+
+### 7. 测试与门禁
+
+确认：
+
+- 单元测试共置的文件后缀。
+- 集成、契约和 E2E 的目录。
+- PR 必跑的 `format:check`、`lint`、`typecheck`、`test`、`build`。
+- 是否运行受影响测试还是全量测试。
+
+固定默认：单元测试共置，缺陷修复需要回归测试，核心门禁不得被删除或跳过。
+
+### 8. 例外和迁移
+
+确认项目如何记录：
+
+- Lint/类型例外说明格式。
+- TODO 的任务编号格式。
+- 临时例外的负责人和删除条件。
+- 历史债务的 Ratchet 指标。
+
+## 结束条件
+
+当以下内容均已确定即可停止提问：
+
+- 目录和命名规则可执行。
+- 类型、安全和运行时验证边界明确。
+- 文件大小与拆分策略明确。
+- 测试位置、命名和门禁明确。
+- 例外和遗留治理明确。
+- 项目特有框架规则已覆盖。
+
+不要为了填满问题数量继续提问。
+
+## 决策摘要格式
+
+```md
+## 自动识别
+- 包管理器：pnpm
+- 模块系统：ESM
+- 测试：Vitest，单元测试已共置
+
+## 用户确认
+- React 组件使用 PascalCase.tsx
+- Barrel 仅用于包公共入口
+
+## 默认基线
+- 领域内部局部平铺
+- 注释解释 WHY
+- 普通 TS 文件软上限 300 行
+
+## 兼容例外
+- generated/ 保留生成器命名，不执行文件大小检查
+```

package/template/skills/typescript-standards-builder/references/03-project-architecture-and-directory-layout.md

@@ -0,0 +1,84 @@
+# 项目架构与目录布局
+
+## 先表达稳定边界
+
+目录优先表达以下一种或组合后的稳定边界：
+
+- 运行环境：`main/`、`renderer/`、`server/`、`worker/`、`cli/`。
+- 产品领域：`user-auth/`、`orders/`、`payments/`。
+- 架构职责：`domain/`、`application/`、`infrastructure/`。
+- 独立发布单元：`apps/`、`packages/`。
+
+对多运行环境项目，通常先隔离运行环境，再在各环境内部按领域组织。
+
+## 领域内部局部平铺
+
+这是生成规范的固定默认原则：一个职责明确的领域目录应优先直接平铺文件，不为每个文件建立同名目录。
+
+推荐：
+
+```text
+features/user-auth/
+├── login-command.ts
+├── login-command.test.ts
+├── login-policy.ts
+├── login-service.ts
+└── user-session.ts
+```
+
+不推荐：
+
+```text
+features/user-auth/
+├── commands/login/login-command.ts
+├── policies/login/login-policy.ts
+└── services/login/login-service.ts
+```
+
+增加子目录的条件：
+
+- 形成稳定、可命名的子领域。
+- 同级文件长期较多，浏览成本明显上升。
+- 文件组拥有独立入口、资源、夹具或生命周期。
+- 文件组需要整体移动、替换或发布。
+- 运行环境或依赖方向要求物理隔离。
+
+阈值应根据项目实际规模确定，不能机械复制通用数字。
+
+## 领域优先，技术类型局部化
+
+小项目可从技术类型目录起步；业务增长后，应把 `components/`、`hooks/`、`services/` 等技术目录移动到对应领域内部。
+
+不要在同一层混用互不相干的分类主轴。
+
+## `shared/` 准入
+
+代码进入共享层前应满足：
+
+1. 至少有两个真实调用方。
+2. 不依赖具体业务领域。
+3. 能用具体名称说明能力。
+4. API 相对稳定。
+5. 不造成反向依赖。
+6. 共享确实减少重复，而非提前抽象。
+
+`shared/` 不是“不知道放哪里”的收容区。
+
+## 多运行环境
+
+- 各环境使用独立 `tsconfig` 或项目引用。
+- 浏览器代码不得意外导入 Node 专属模块。
+- 服务端代码不得无意依赖 DOM。
+- 跨环境数据通过显式、可序列化、可版本化契约。
+- 桥接 API 最小化，并验证所有边界输入。
+
+不要把 Electron 专属的 `main/preload/renderer` 目录复制到普通项目；只在实际存在这些运行环境时采用。
+
+## 拆分信号
+
+- 一个目录同时包含多个运行环境。
+- 改动一个领域经常触发无关领域。
+- 文件名需要大量前缀才能区分。
+- 公共入口持续扩大。
+- 依赖图出现循环。
+- 不同部分需要不同构建、发布或权限策略。

package/template/skills/typescript-standards-builder/references/04-file-directory-and-symbol-naming.md

@@ -0,0 +1,92 @@
+# 文件、目录与标识符命名
+
+## 文件名必须具体
+
+这是固定默认原则。文件名应表达“领域 + 职责”，使搜索结果和代码评审无需打开文件即可理解用途。
+
+推荐：
+
+- `user-session-store.ts`
+- `payment-retry-policy.ts`
+- `terminal-output-parser.ts`
+- `github-auth-client.ts`
+- `workspace-path-validator.ts`
+
+默认禁止把不相关能力堆进：
+
+- `utils.ts`
+- `helpers.ts`
+- `common.ts`
+- `misc.ts`
+- `general.ts`
+- `manager.ts`
+- `processor.ts`
+- `handler.ts`
+- 全局 `types.ts`
+- 全局 `constants.ts`
+
+父目录已经提供完整语义时，局部 `types.ts` 可以作为兼容例外；仍优先考虑可搜索的具体名称。
+
+## 默认命名
+
+项目生成时必须结合仓库事实确认，常用基线为：
+
+| 对象 | 默认规则 | 示例 |
+|---|---|---|
+| 目录 | `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` |
+
+生成器或框架管理的文件可保留其约定，必须在项目规范中标出适用范围。
+
+## 职责后缀
+
+- `-service`：完整应用能力，不得成为万能类。
+- `-repository`：领域对象的持久化抽象。
+- `-client`：外部 HTTP、RPC 或 SDK 客户端。
+- `-adapter`：接口或模型适配。
+- `-gateway`：外部系统或资源边界。
+- `-store`：状态保存和更新。
+- `-selector`：状态派生。
+- `-policy`：可替换业务决策。
+- `-validator`：验证输入。
+- `-parser` / `-serializer`：格式转换。
+- `-mapper`：明确模型之间映射。
+- `-factory`：复杂对象或依赖图构造。
+- `-registry`：实现注册和查找。
+- `-scheduler`：任务调度。
+- `-coordinator`：多个流程协调。
+- `-contract`：跨模块、跨进程或公开 API 契约。
+
+后缀不能替代领域信息。单独的 `service.ts` 仍然模糊。
+
+## 标识符
+
+- 变量、函数、方法：`camelCase`。
+- 类型、类、组件：`PascalCase`。
+- 真正常量：`SCREAMING_SNAKE_CASE`。
+- 私有字段：`#field` 或 `private`，不加无意义 `_`。
+- Hook：`useXxx`。
+- 事件属性：`onXxx`。
+- 内部事件处理：`handleXxx`。
+- 泛型：简单时 `T`，复杂时 `TResult`、`TContext`。
+
+## 布尔与单位
+
+布尔值优先：`isConnected`、`hasAccess`、`canRetry`、`shouldPersist`。
+
+数值名称包含单位或语义：
+
+```ts
+const timeoutMs = 30_000
+const payloadSizeBytes = 1_024
+const retryCount = 3
+```
+
+避免 `flag`、`data`、`info`、`obj`、`temp` 等无信息名称。

package/template/skills/typescript-standards-builder/references/05-modules-imports-exports-and-dependencies.md

@@ -0,0 +1,63 @@
+# 模块、导入、导出与依赖
+
+## 命名导出优先
+
+默认使用命名导出。默认导出仅用于：
+
+- 框架规定的页面、路由或配置入口。
+- 工具链要求的入口。
+- 仓库已经形成且用户确认保留的惯例。
+
+## 一个文件一个主要公开概念
+
+一个文件可以包含少量私有辅助函数，但通常只公开一个主要能力或一组高度相关能力。达到独立职责的辅助逻辑应拆为具体命名文件，不得拆成新的 `helpers.ts`。
+
+## Barrel 文件
+
+允许 `index.ts`：
+
+- 作为包或领域的明确公共入口。
+- 隐藏内部实现并稳定外部 API。
+- 作为依赖装配或框架入口。
+
+禁止：
+
+- 每个目录机械创建 `index.ts`。
+- 建立全项目万能 Barrel。
+- 暴露内部实现。
+- 用 Barrel 隐藏循环依赖。
+
+## 导入
+
+常用顺序：Node 内置、第三方、项目别名、相对路径、类型导入。具体顺序由项目格式化或 Lint 工具执行。
+
+要求：
+
+- Node 内置模块使用 `node:` 前缀。
+- 仅作为类型使用时采用 `import type`。
+- 不保留未使用和重复导入。
+- 副作用导入必须有明确原因。
+- 路径别名对应稳定边界，不用于任意跨层跳转。
+
+## 依赖方向
+
+推荐：
+
+```text
+UI / Entry
+    ↓
+Application orchestration
+    ↓
+Domain
+    ↓
+Ports / contracts
+    ↑
+Infrastructure adapters
+```
+
+- 领域逻辑不直接依赖数据库、HTTP、文件系统或 UI 框架。
+- 共享模块不依赖具体领域。
+- 底层模块不反向导入界面层。
+- 跨环境调用通过显式契约和适配器。
+
+循环依赖必须作为架构问题处理，而不是调整导入顺序掩盖。

package/template/skills/typescript-standards-builder/references/06-typescript-type-system.md

@@ -0,0 +1,64 @@
+# TypeScript 类型系统规范
+
+## 严格模式
+
+新项目必须启用 `strict`。成熟项目根据现状制定分阶段迁移，但新代码不得继续增加宽松类型债务。
+
+建议评估：
+
+- `noUncheckedIndexedAccess`
+- `exactOptionalPropertyTypes`
+- `noImplicitOverride`
+- `noImplicitReturns`
+- `noFallthroughCasesInSwitch`
+- `useUnknownInCatchVariables`
+- `verbatimModuleSyntax`
+- `isolatedModules`
+- `forceConsistentCasingInFileNames`
+
+必须与当前编译器、模块系统和构建工具兼容。
+
+## 外部输入使用 `unknown`
+
+HTTP、RPC、WebSocket、IPC、CLI 参数、环境变量、JSON、数据库反序列化、本地存储、第三方 SDK 和插件输入默认不可信。
+
+类型断言不能替代运行时验证。优先使用项目已存在的 Schema 库或明确类型守卫，不擅自引入新依赖。
+
+## 禁止传播 `any`
+
+`any` 仅允许存在于极小兼容层，并满足：
+
+- 最小作用域。
+- 有原因和退出条件。
+- 经过运行时验证后再向内部传递。
+- 不进入公共 API。
+
+## 可辨识联合
+
+互斥状态使用单一判别字段，避免多个可能矛盾的布尔值。状态分支执行穷尽检查。
+
+## `type` 与 `interface`
+
+由问答确定项目默认偏好。无项目事实时推荐：默认使用 `type`；需要声明合并、公开扩展或明确 `implements` 契约时使用 `interface`。
+
+## 类型标注
+
+必须显式标注：
+
+- 导出函数返回类型。
+- 跨模块公共 API。
+- 插件、回调和扩展点。
+- 递归函数。
+- 权限、金额、状态转换等高风险函数。
+
+局部明显变量可依赖推断。
+
+## 断言、空值和声明文件
+
+优先顺序：控制流收窄、类型守卫、运行时验证、`satisfies`、最后才使用 `as`。
+
+禁止无理由双重断言和 `@ts-ignore`。必须压制时使用带原因的 `@ts-expect-error`。
+
+明确区分可选属性、`null`、`undefined` 和失败结果。
+
+`.d.ts` 只用于环境、模块、声明扩展和发布声明；普通业务类型放在 `.ts`。

package/template/skills/typescript-standards-builder/references/07-functions-async-errors-and-resources.md

@@ -0,0 +1,42 @@
+# 函数、异步、错误与资源生命周期
+
+## 函数职责
+
+函数只处理一个可命名职责和一个抽象层级。项目规范可设置函数行数、嵌套和参数数量的软预算，但不得为满足数字做无意义拆分。
+
+- 使用 Guard Clause 减少嵌套。
+- 长参数列表和布尔参数改为具名参数对象。
+- 分离解析、验证、领域决策、I/O 和流程编排。
+- 纯逻辑不读取隐藏全局状态，不修改输入。
+
+## Promise 必须有归宿
+
+所有 Promise 必须被 `await`、`return`、显式收集，或用 `void` 明确脱离当前流程并自行处理错误。
+
+只有互相独立的任务才使用 `Promise.all`。大型输入不得无界并发。
+
+## 取消、超时与重试
+
+网络、子进程、文件监听、Worker 和长任务应考虑：
+
+- `AbortSignal`。
+- 明确超时。
+- 清理路径。
+- 可识别取消错误。
+- 超时后底层资源是否真正停止。
+
+重试必须定义最大次数、退避、抖动、可重试错误和幂等性。
+
+## 错误
+
+不得吞掉异常。错误应包含操作上下文并保留 `cause`。
+
+调用方需要分支处理的错误使用具名错误类、结构化 `code`、`Result<T, E>` 或可辨识联合，不匹配错误消息字符串。
+
+`catch` 值视为 `unknown`，先收窄再处理。
+
+## 资源清理
+
+事件监听器、Timer、文件句柄、Socket、数据库连接、Worker、子进程、`AbortController` 和 React Effect 订阅必须有明确生命周期。
+
+创建资源的模块通常负责定义或暴露清理方式，可返回清理函数或实现 `dispose()`。

package/template/skills/typescript-standards-builder/references/08-comments-jsdoc-and-documentation.md

@@ -0,0 +1,51 @@
+# 注释、JSDoc 与文档
+
+## 注释必须关注 WHY
+
+这是固定默认原则。注释用于解释代码无法直接表达的原因和约束：
+
+- 为什么必须采用此顺序。
+- 为什么不能删除看似多余的逻辑。
+- 平台、协议、性能或安全约束。
+- 第三方缺陷和规避方案。
+- 竞态条件和资源生命周期。
+- 非直观产品规则。
+
+不逐行翻译代码，不用注释补救模糊命名或过大模块。
+
+## 风格
+
+- 优先一行或短段落。
+- 靠近被解释逻辑。
+- 原因必须具体、可验证。
+- 修改实现时同步更新。
+- 看似特殊的兼容或性能逻辑应说明删除条件。
+
+## 不应提交
+
+- 注释掉的旧代码。
+- 无跟踪信息的“以后优化”。
+- 与实现重复的大篇教程。
+- 无法验证的猜测。
+
+## JSDoc
+
+主要用于：
+
+- 公共库 API。
+- 插件和扩展点。
+- 跨团队、跨包或跨进程契约。
+- 参数有单位、边界或特殊格式。
+- 函数有重要副作用、取消或异常语义。
+
+内部显而易见函数不机械添加 JSDoc。
+
+## TODO 与设计文档
+
+TODO 必须符合项目确认的任务编号格式并说明删除条件，例如：
+
+```ts
+// TODO(PROJ-1423): Remove after all clients send protocol v3.
+```
+
+多方案权衡、迁移计划和长期架构放入 `docs/` 或 ADR；源码注释只保留理解当前实现所需的最小上下文。

package/template/skills/typescript-standards-builder/references/09-testing-strategy.md

@@ -0,0 +1,58 @@
+# 测试策略
+
+## 单元测试靠近实现
+
+这是固定默认原则：单元测试与源文件共置，便于发现、移动、重命名和维护。
+
+```text
+shell-command-quote.ts
+shell-command-quote.test.ts
+```
+
+跨模块集成、契约和 E2E 测试集中管理，例如：
+
+```text
+tests/
+├── integration/
+├── contracts/
+└── e2e/
+```
+
+生成项目规范时应根据现有框架确认实际后缀和目录，不机械复制示例。
+
+## 测试命名
+
+测试名描述可观察行为，不描述实现步骤。禁止 `it('works')` 和 `describe('utils')`。
+
+## 覆盖范围
+
+关键模块考虑：
+
+- 正常路径。
+- 边界和空输入。
+- 无效输入。
+- 错误传播。
+- 取消和超时。
+- 并发或重复调用。
+- 资源清理。
+- 已修复缺陷的回归场景。
+
+## 缺陷修复
+
+1. 添加稳定复现问题的失败测试。
+2. 确认修复前失败。
+3. 实施最小修复。
+4. 确认回归和相关测试通过。
+5. 必要时增加跨平台或集成测试。
+
+## 确定性与 Mock
+
+测试不依赖真实当前时间、外部不稳定网络、执行顺序、共享可变全局状态、本机特定路径或无种子随机数。
+
+Mock 系统边界，不 Mock 被测模块每个内部调用。优先测试真实纯函数和可观察行为。
+
+## 质量门禁
+
+- 不得为使 CI 通过而删除或长期跳过失败测试。
+- 新功能和缺陷修复必须按风险补充测试。
+- 测试代码同样遵守清晰命名、资源清理和大小预算。

package/template/skills/typescript-standards-builder/references/10-react-and-frontend.md

@@ -0,0 +1,39 @@
+# React 与前端规范
+
+仅在项目实际使用 React 或类似组件框架时生成本模块。
+
+## 组件
+
+- Props 明确表达输入，渲染尽量纯粹。
+- 数据获取、业务状态编排、领域交互和视觉展示按复杂度拆分。
+- 组件使用具体领域名称，避免 `CommonModal`、`GenericPanel`。
+- 组件文件命名由仓库事实或用户问答确认。
+
+## Props 与 Hook
+
+- Props 类型使用项目统一命名，如 `XxxProps`。
+- 布尔 Props 使用 `is`、`has`、`can`、`should`。
+- 事件 Props 使用 `onXxx`。
+- 复杂互斥状态使用联合类型，不用多个布尔值构造隐式状态机。
+- 自定义 Hook 以 `use` 开头，一个 Hook 一个可命名职责。
+- Effect 依赖完整，创建资源时返回清理函数。
+
+## 状态和 Effect
+
+- 状态尽量靠近使用位置。
+- Store 按领域切片，不创建单一巨型 Store。
+- 派生数据优先计算，不重复存储。
+- Effect 用于与外部系统同步，不替代普通计算。
+- 异步 Effect 考虑取消、竞态和过期响应。
+
+## 性能与可访问性
+
+- 不滥用 `memo`、`useMemo`、`useCallback`。
+- 优化基于测量或已识别瓶颈。
+- 长列表使用虚拟化，高频事件使用调度或节流。
+- 使用语义化 HTML，交互支持键盘，图标按钮有可访问名称。
+- 不以颜色作为唯一状态表达。
+
+## 浏览器边界
+
+验证 URL、消息、Storage 和第三方脚本输入；不把秘密放入前端 Bundle；不直接导入 Node 专属模块，除非平台提供受控桥接。

package/template/skills/typescript-standards-builder/references/11-node-cli-and-cross-platform.md

@@ -0,0 +1,31 @@
+# Node.js、CLI 与跨平台规范
+
+仅在项目实际包含 Node.js、CLI、Electron 主进程或服务端代码时生成相关部分。
+
+## 路径和文件系统
+
+- 使用 `node:path` 等标准 API，不手工拼接平台路径。
+- 考虑 Windows 分隔符、盘符、UNC、符号链接、路径遍历和大小写差异。
+- 文件操作明确编码、原子性、权限和清理路径。
+
+## CLI
+
+- 参数解析、验证、命令执行和错误渲染分离。
+- 错误写入 `stderr`，机器可读正常输出写入 `stdout`。
+- 明确定义退出码。
+- 底层领域逻辑不直接调用 `process.exit()`。
+- 信号处理和资源清理集中管理。
+
+## 环境变量
+
+在启动边界一次性读取、验证和标准化环境变量，转换为只读配置对象。业务代码不得在各处直接访问 `process.env`。
+
+## 子进程和 Shell
+
+- 优先使用参数数组而非拼接 Shell 字符串。
+- 明确超时、取消、信号、输出上限和清理。
+- 用户输入不得未经转义进入命令。
+
+## 多运行环境
+
+Node、浏览器、Electron 主进程、预加载和 Worker 使用独立类型与构建配置。只复制实际存在的运行环境结构，不机械创建不相关目录。