效果语言服务
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- Bun
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Effect Language Service
Operational guide for `@effect/language-service` CLI and configuration. This skill handles
**tooling**: running commands, interpreting output, applying fixes, configuring projects.
For architecture decisions about when/how to use Effect, see `effect-usage-cc` instead.
## Command Decision Table
Always run from the **project root** via the local binary (`bunx effect-language-service` or
`./node_modules/.bin/effect-language-service`). Commands like `check` resolve paths relative
to cwd — running from a subdirectory breaks them.
| Intent | Command | Key flags |
|---|---|---|
| Check for Effect issues | `diagnostics --project tsconfig.json` | `--format pretty` human, `--format json` parseable |
| Check single file | `diagnostics --file <path>` | Faster than full project scan |
| See available fixes | `quickfixes --project tsconfig.json` | `--code <rule>` filter by rule |
| Fix specific issue | `quickfixes --file <path> --line <n> --fix <fixName>` | Shows diff to apply |
| Generate from directives | `codegen --project tsconfig.json` | `--force` regenerates all |
| Understand project structure | `overview --project tsconfig.json` | `--max-symbol-depth 2` (depth 3 adds noise) |
| Analyze layer composition | `layerinfo --file <path> --name <Layer>` | Outputs composition order |
| Check TS patch status | `check` | Verifies patch version |
| Patch TypeScript for tsc | `patch` | `--force` re-patches |
| Interactive setup | `setup` | Wizard for first-time config |
| Configure rule severities | `config` | Interactive severity editor |
| CI gate | `diagnostics --format github-actions --strict` | Non-zero exit on warnings |
## Interpreting Output
### Diagnostic format
```
src/service.ts:42:3 effect(floatingEffect): This Effect is not yielded or assigned
```
Structure: `file:line:col effect(ruleName): message`. The `ruleName` maps directly to the
`diagnosticSeverity` config key in tsconfig.json and to the inline suppression syntax.
### Quickfix format
Output: diagnostic line followed by one or more unified diffs per available fix. Each fix
has a `fixName` (e.g., `floatingEffect_yieldStar`) that can be used with `--fix` to filter.
### Severity levels
- **error** — Must fix. Blocks CI (always non-zero exit)
- **warning** — Should fix. Blocks CI only with `--strict`
- **message/suggestion** — Informational. Never blocks CI even with `--strict` (emits
`::notice` in github-actions format, not `::error`). Only blocks tsc if `includeSuggestionsInTsc` enabled
## Key Workflows
### Fix all issues in a file
```bash
# 1. See what's wrong
effect-language-service diagnostics --file src/service.ts --format pretty
# 2. See available fixes with diffs
effect-language-service quickfixes --file src/service.ts
# 3. Filter to a specific rule
effect-language-service quickfixes --file src/service.ts --code floatingEffect
```
Review the diffs before applying. Correctness fixes (floatingEffect, missingReturnYieldStar)
are safe to apply. Style fixes (effectMapVoid, unnecessaryPipe) are preferences — check
project conventions.
### Onboard a new project
```bash
# 1. Interactive setup (patches TS, configures tsconfig)
effect-language-service setup
# 2. Persist patch across installs
# Add to package.json scripts: "prepare": "effect-language-service patch"
# 3. Baseline scan
effect-language-service diagnostics --project tsconfig.json --format pretty
```
### LLM context generation
`overview` and `layerinfo` produce text output (no `--format json` — only `diagnostics`
supports `--format`). Both emit ANSI spinner noise that must be stripped.
**Clean extraction pattern** (use for all text-output commands):
```bash
# Strip ANSI codes and spinner lines from any ELS text command
els_clean() {
effect-language-service "$@" 2>/dev/null \
| sed 's/\x1b\[[0-9;]*m//g' \
| grep -v "^Processing file"
}
# Project map: services, layers, yieldable errors
els_clean overview --project tsconfig.json --max-symbol-depth 2
# Specific layer: provides, requires, composition order
els_clean layerinfo --file src/layers.ts --name AppLayer
# Full snapshot: overview + diagnostics + quickfixes in one shot
els_clean overview --project tsconfig.json --max-symbol-depth 2 > /tmp/els-overview.txt
effect-language-service diagnostics --project tsconfig.json --format json > /tmp/els-diag.json
els_clean quickfixes --project tsconfig.json > /tmp/els-fixes.txt
```
`overview` groups exports into "Yieldable Errors", "Services", "Layers" with file+line,
type info, and JSDoc. **Warning**: each symbol appears at every re-export point (barrel
files, index.ts). Deduplicate by source `file:line` — expect ~40% noise from duplicates
in large projects.
`layerinfo` outputs a suggested `Layer.provide` / `Layer.provideMerge` composition.
Requires a **named, exported Layer** — anonymous or inline layers are not supported.
Tip: write all layers in `Layer.mergeAll(...)`, run `layerinfo`, use the suggested order.
## Guardrails
1. **Scope your scans** — Use `--file` when working on a single file. Full `--project` scans
are slow in large codebases and produce noise from files you're not touching.
2. **Review quickfix diffs** — Correctness fixes are generally safe. Style fixes may conflict
with project conventions. Anti-pattern fixes sometimes need manual adjustment.
3. **Monorepo tsconfig** — Always specify `--project` explicitly. Without it, ELS infers
the tsconfig which may be wrong in monorepos with multiple configs.
4. **codegen --force caution** — Regenerates ALL directives in the project. Use `--file` to
scope to a single file. Manual edits to generated blocks will be overwritten.
5. **Patch persistence** — The TS patch modifies `node_modules/typescript/`. It disappears
after `npm install`/`bun install`. Use `"prepare": "effect-language-service patch"` to
persist it.
6. **diagnostics vs tsc** — Without patching, `tsc` does NOT run Effect diagnostics. The
`diagnostics` CLI command works without patching. The patch is only needed for `tsc`
integration and IDE features.
7. **ANSI spinner pollution** — `overview`, `layerinfo`, and `quickfixes` emit ANSI escape
codes and "Processing file" spinner lines mixed into stdout. Always pipe through the
`els_clean` pattern (strip ANSI + filter spinner) when capturing output programmatically.
8. **--format is diagnostics-only** — Only `diagnostics` supports `--format json|text|pretty|github-actions`.
All other commands (`overview`, `layerinfo`, `quickfixes`, `codegen`) output unstructured
text. Do not waste time trying `--format` on them.
9. **codegen with no directives** — If no files contain `@effect-codegens`, `codegen` throws
`NoFilesToCodegenError` instead of exiting cleanly. This is not a real error — the project
simply has no codegen directives. Check before running.
10. **config/setup file picker** — Both `config` and `setup` are interactive and list ALL `.json`
files in the project, not just tsconfig files. This is a known UX issue — select the
correct tsconfig manually.
## Fetching Documentation
This skill covers tooling operations. For current API details or version-specific changes:
| Need | Tool |
|---|---|
| ELS release notes, new rules | `mcp__exa__web_search_exa` — search Effect-TS/language-service |
| Effect API docs | `mcp__Context7__query-docs` — resolve `effect` library |
| Pattern guidance | Load `effect-usage-cc` skill |
## Navigating References
Load references when the command table and workflows above are insufficient.
| File | Answers |
|---|---|
| `references/cli-commands.md` | Full syntax for each command? All flags and defaults? |
| `references/diagnostic-rules.md` | What does rule X mean? How to fix it? Default severity? |
| `references/refactorings.md` | Which IDE refactoring to use? async→Effect variants? |
| `references/codegen-directives.md` | How to use @effect-codegens? When to annotate/accessors/typeToSchema? |
| `references/configuration.md` | All tsconfig options? Severity profiles? CI setup? Inline suppression? |
!`echo "## ELS Project Context"`
!`~/.claude/skills/effect-language-service-cc/scripts/probe-els.sh`
---
> Source: [bengous/agents-skills](https://github.com/bengous/agents-skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
章节与文件索引
按说明文件中的顺序排列。
命令决策表
诊断格式
快速修复格式
严重程度
修复文件中的所有问题
文件/命令 -> @effect/language-service · effect-usage-cc · bunx effect-language-service · ./node_modules/.bin/effect-language-service · check · diagnostics --project tsconfig.json · --format pretty · --format json
内容校验值 -> 83d6617bd127
当前原文的自动摘译,尚未人工审校。
命令决策表
始终通过本地二进制文件(
bunx effect-language-service或./node_modules/.bin/effect-language-service)从项目根运行。像check这样的命令解析相对于cwd的路径——从子目录运行会破坏它们。意图·命令·关键标志检查效果问题·diagnostics --project tsconfig.json·--format pretty人类,--format json可解析诊断格式
结构:
file:line:col effect(ruleName): message。ruleName直接映射到 tsconfig.json 中的diagnosticSeverity配置键以及内联抑制语法。快速修复格式
输出:诊断行,后跟每个可用修复的一个或多个统一差异。每个修复都有一个
fixName(例如,floatingEffect_yieldStar),可以与--fix一起使用进行过滤。严重程度
错误——必须修复。阻止 CI(始终非零退出)警告 — 应该修复。仅通过
--strict消息/建议阻止 CI — 信息性的。即使使用--strict也不会阻塞 CI(以 github-actions 格式发出::notice,而不是::error)。如果includeSuggestionsInTsc启用,则仅阻止 tsc修复文件中的所有问题
在申请之前查看差异。正确性修复(floatingEffect、missingReturnYieldStar)可以安全应用。样式修复(effectMapVoid、unknownPipe)是首选项 - 检查项目约定。