# @encore-os/eos-spec 中文文档

规范地址：https://npmcn.com/package/%40encore-os/eos-spec/

版本：0\.33\.2
npm 元数据更新时间：2026-10-17T10:56:08.309Z
中文译文更新时间：2026-11-13T17:32:56.765Z
软件包许可：SEE LICENSE IN LICENSE

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40encore-os/eos-spec
原文对照：https://npmcn.com/package/%40encore-os/eos-spec/?lang=original
项目主页：https://github.com/Encore-OS/eos-spec-core#readme
源码仓库：https://github.com/Encore-OS/eos-spec-core

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.1 MB，431 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：2 个
- peer 依赖：yaml ^2\.8\.4
- 首次发布：2026-06-22T19:14:52.379Z
- 最新版本发布：2026-10-17T10:56:08.149Z
- 近 30 天下载量：3517（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：43（近 12 个月 43 个）

## 中文简介

可移植,可配置驱动的光谱管引擎+质量牵引. 由Encore-OS repo公司作为库所消耗的一款犬形引擎(带有客户安全/纯子路径).

## 安装

```sh
npm install @encore-os/eos-spec
```

也可以使用：`pnpm add @encore-os/eos-spec`、`yarn add @encore-os/eos-spec`、`bun add @encore-os/eos-spec`

## README

# @encore-os/eos- spec

便携式、由配置驱动 **spec-pipeline 引擎 + 质量牵引**二号船 组合中的相片: 方便代理的 CLI(`eos-spec`)和一个图书馆(有一个 浏览器安全 `/pure` (原始内容存档于2018-09-29). Subpath. 软件包没有实体数据——它驱动任何 转帐 `specs/` 树的描述,雷波's `specs/config.yaml`。 。 。 .

光谱通过管道移动( S)`stub → clarified → validated → … → tasks_generated`);引擎从它的信号中获取每个光谱的相位 建议下一步行动(认识到障碍)和大门完成索赔 与磁盘上的证据相反.

## 快速启动 — 有编码代理( 建议)

```bash
npm install -D @encore-os/eos-spec   # or run everything via npx
npx @encore-os/eos-spec setup        # prints the onboarding plan
npx @encore-os/eos-spec setup --yes  # scaffold layout + AI_GUIDE.md + install spec-pipeline-skills (Claude Code)
```

那就让你的经纪人如. _"读取AI GUIDE.md并使用eos-spec来创建和 开一个spec for"_ 生成的 `AI_GUIDE.md` 教会代理 循环 : `profile --json` 先说 `next` 编号 : `run`永远 `--json`打开 机器错误代码.

## 快速启动——手工

```bash
npx @encore-os/eos-spec init --scaffold      # specs/config.yaml + templates + per-core dirs
npx @encore-os/eos-spec create APP-01 "First feature"   # `app` is the scaffolded default core
npx @encore-os/eos-spec validate --core app
npx @encore-os/eos-spec next --spec APP-01   # the one recommended next action
```

`eos-spec --help` 列出每个命令的示例.

## 机器合同

每个命令都接受 `--json` 并发出一个稳定的信封:

```json
{ "ok": true, "data": { "…": "…" } }
{ "ok": false, "data": null, "error": { "code": "SPEC_NOT_FOUND", "message": "…" } }
```

出错代码是一个被冻结的,仅附加的enum(`SPEC_NOT_FOUND`, (中文(简体) ), `UNKNOWN_CORE`, (中文(简体) ), `INVALID_ARGUMENT`, (中文(简体) ), `SCOPE_REQUIRED`, (中文(简体) ), `VALIDATION_FAILED`, (中文(简体) ), `DUPLICATE_SPEC_ID`, (中文(简体) ), `SUBPROCESS_ERROR`, (中文(简体) ), `IO_ERROR`, (中文(简体) ), `ENGINE_VERSION_MISMATCH`, (中文(简体) ), `INTERNAL`, (中文(简体) ), `GATE_HALT`(b) —— 打开 `error.code`,从不记录文本. `GATE_HALT` 实值 `run` 停止在一个 守法/研究治理门 它永远不会清除: 一个人类清除它,然后重新运行. 将 CLI 连接到它们所支持的引擎范围的技能 `--require-engine ">=0.23 <1"` 旗帜; 不匹配迅速失败 `ENGINE_VERSION_MISMATCH`。 。 。 .

## 入境点

-   **`@encore-os/eos-spec`** - fs-约束主条目:CLI方案外加实体 API (英语:`listSpecs`, (中文(简体) ), `findSpec`, (中文(简体) ), `loadConfig`(中文(简体) ).
-   **`@encore-os/eos-spec/pure`** ——只允许自由再出口;安全捆绑在一个 浏览器应用。通过对过渡值进口的纯度测试执行.
-   **`@encore-os/eos-spec/embeddings`** - 狭长的由fs捆绑的子路径,用于生物-局部 嵌入式构建 + recover, 不在 CLI 图表中拖放 .

## 以往语义搜索( S)

这个 `precedent` 命令搜索活动 + 存档的光谱、 注册和推迟 前作的仪表板 :

-   **`precedent --spec <id>`** ——查询一个规格的先例(标识符重叠). 返回共享后置引用的表格标识符,按文档排序 频率(清晰的共享表格排序较高).
    
-   **`precedent --topic <text>`** - 专题关键词查询先例(排名 搜索) (中文(简体) ). 等级结果 **当有矢量+嵌入器时** (通过嵌入 Ollama 的实时查询); **逻辑倒置** 当其中之一 缺席。 输出带有 `rankMode` 字段 (`'semantic'` 或者说 `'lexical'`改为: 信号哪种方法对点击进行排序。 当排列时, 存档的规格 不在嵌入体中;状态元数据可能显示 `'unknown'` 页:1 语义击出.
    

两种模式支持 `--core <core>` 到一个核心。 这个 `--all` 旗帜 解除默认的上限( 上等匹配 ) .

### 创建关卡: 先例块模式

Repos 可以声明 `create_gates` 块中 `specs/config.yaml` 选择加入 **块模式** 联 合 国 `create` 命令的 Tier-2 先例自动检查 :

```yaml
create_gates:
  precedent: block            # 'warn' (default) | 'block'
  precedent_block_min_score: 12
```

-   `precedent: 'warn'` (默认) — Surfaces prefer arts 但绝不是块. 显示顶端 当一个 spec ID 或 标题有近似重复的先例时,语法点击.
    
-   `precedent: 'block'` —— 说 **停车 `create`** (非零出口,无脚手架) 顶级词汇击出分数 `precedent_block_min_score`编辑 `--force` 旗帜 超过(已登录) 。 配置/ 搜索错误失败打开 .
    
-   `precedent_block_min_score` - 底分表(搜索Specs) `score` 字段); 默认为12。 光凭头衔的比赛永远不能达到12个——地板要求 真正的双标志性证明(标题和正文)。 过 `create <id> --force` 改为 创造力量,尽管有很高的先例.
    

每次引用都会记录一个创建前的门事件,无论 检查是警告还是屏蔽.

### 门触发器: `triggers:` 块

将门或盖(管制、敏感、, 包含UI)和遵守开关在 `specs/config.yaml`每把钥匙 是可选的; 缺省块或密钥保留此处显示的引擎默认值 :

```yaml
triggers:
  regulated_cores: [cl, pm, hr, rh, gr]   # each must be a core declared in `cores:`; [] = none
  sensitive_tags: [sensitive, phi, pii, billing, credentialing]
  sensitive_fields: []                    # frontmatter keys; `phi: true` opts a spec in
  sensitive_keywords: true                # the HIGH/LOW content heuristic
  ui_paths: ['\/(components|pages|wizards)\/', '\.tsx$']   # over each affected_files entry
  ui_headings: ['UI\s*(?:\/\s*)?UX\b']    # an h1–h3 heading TITLE (see "UI sources" below)
  ui_id_patterns: ['-UX-']                # over the resolved spec id, case-insensitive
  ui_ux_dir: true                         # a spec under specs/<core>/ux/ is a UI source
  ui_inference: warn                      # off | warn ('cap' is reserved and rejected)
  compliance: true                        # D12: only a literal `false` turns compliance gating off
```

-   **校验严格而故障闭.** 一个未知的密钥, 一个没有值的密钥, 非清单、空白条目、未申报的核心、引文 `"false"`,或外部图案 引擎的线性时间正则ex子集失败了每个命令 `VALIDATION_FAILED` (exit 2)并列出每个问题; `doctor` 报告为调查结果。 一个引擎 以验证块拒绝它不知道的密钥,所以使用密钥的配置 从较新的引擎那里响亮地失败; 引擎在块存在之前释放 完全无视它(遵守规定和遵守规定)。 对一个配置 依赖密钥 `--require-engine`。 。 。 .
-   **模式** 使用安全子集:无外观、回溯、计数或懒惰 重复,嵌入式重复,或相邻的可匹配相同的修饰符 字符( c)`\s*\/?\s*`, (中文(简体) ), `a*a*`;最多200个字符和16个限定词.
-   **关键字扫描读取整个文件, 包括前题**,所以一个 `tags: [phi]` 线条保持 spec 关键字敏感,即使 `phi` 没有在 `sensitive_tags`A级 无标签敏感度定义也设置 `sensitive_keywords: false`。 。 。 .
-   **`compliance: false`** 在一个地方关闭遵守度显示: 遵守审查阶段停止适用, `isComplianceGated` 实值 `false` 内 `next`编号 :`status` 乔森, `run` 从不严格行走, 背填预置数为 spec 检查,关闭 永远不会限制一个缺失的遵守签注。 分类者 它们本身不会改变.
-   **UI来源.** 一个光谱是UI(UX盖和UI-证据尾部适用),当 这些控股: `ui_bearing: true`; 一个 `affected_files` 条目匹配 `ui_paths`; 标题匹配 `ui_headings`,平面或后段编号 (单位:千美元)`## UI/UX`, (中文(简体) ), `## 5. UI/UX`, (中文(简体) ), `### 8A) UI / UX`);其编号匹配 `ui_id_patterns`;或 ;或 它活在水下 `specs/<core>/ux/` 时 `ui_ux_dir` 开始 只有一个来源 _推断_: 命名 UI 路径( 非测试) 的机构 `.tsx` 文件,或一个 `src/` 或者说 `@/` 路径 `components/`, (中文(简体) ), `pages/` 或者说 `wizards/`) (中文(简体) ). 从来没有盖过 在一个谱系上 没有UI,没有 `ui-gate-waived`它只发出警告 `ui-inferred-undeclared` 注: 声明 `ui_bearing: true`,或 `eos-spec signoff --type ui-gate-waived --spec <ID>`。注解出现在 `next`编号 :`status` (单位:千美元)`data.triggers`, (中文(简体) ), `data.triggerNotes`, (中文(简体) ), `data.triggerNoteCounts`, (中文(简体) ), `audit` (单位:千美元)`rows[].advisory` 和警告的区块 `doctor` (单位:千美元)`data.advisories`) (中文(简体) ). 它永远不会改变一个动作, `ok` 或一个退出代码.
-   **关闭UI源头.** `ui_inference: off` 跳过只检查身体路径的扫描 关闭音符; 每一个其它源仍然使光谱具有UI. 这些是 用自己的钥匙切换 : `ui_id_patterns: []`, (中文(简体) ), `ui_ux_dir: false`,或缩窄 `ui_headings` 或者说 `ui_paths` 清单(a) `ui_headings` 条目匹配平原和 编号标题)。 对于单一的规格, `eos-spec signoff --type ui-gate-waived --spec <ID>` 升起UX盖和 UI-证据尾部;光谱会保持UI的内含.
-   光谱标记( A)`<!-- sensitive -->`, (中文(简体) ), `<!-- not-sensitive -->`, (中文(简体) ), `ui_bearing: true`, (中文(简体) ), `<!-- ui-gate-waived: -->`永远是荣耀.
-   `profile --json` 解析块为 `triggers`。这些命令读取 从 `--config` 文件 : `next`, (中文(简体) ), `status`, (中文(简体) ), `run`, (中文(简体) ), `proceed`, (中文(简体) ), `reconcile`, (中文(简体) ), `funnel`, (中文(简体) ), `signoff`, (中文(简体) ), `close-out`, (中文(简体) ), `backfill`, (中文(简体) ), `scorecard` (与 `--rtm`, (中文(简体) ), `readiness-rollup`, (中文(简体) ), `mission-status`, (中文(简体) ), `list`, (中文(简体) ), `audit`, (中文(简体) ), `complete`, (中文(简体) ), `doctor` 财务报告和审定财务报表 `profile`其余部分 (单位:千美元)`ready`, (中文(简体) ), `validate`, (中文(简体) ), `walkthrough`, (中文(简体) ), `precedent`, (中文(简体) ), `create`,从 `specs/config.yaml`,正如他们的核心清单所做的那样。 当其中一人行走光谱 实体, 无效的块 `VALIDATION_FAILED` (exit 2) 甚至当 `--config` 命名有效文件; `create` 然后脚手架什么也没有.

### UI- 证据腿( 每条布局)

一个UI的光谱在完成前就欠UI的证据. 默认的腿是道克肖特,a 浏览器自动愈合签出( n)`heal-verified`)和被拍到的走行道(英语:`video-walkthrough`, (中文(简体) ), 或者说 `walkthrough-waived`(三); `ui-gate-waived` 逃脱了他们所有人.

-   **腿是布局数据**,而非配置 : `PipelineSchema.uiEvidence` 宣布双腿 排版欠债,按顺序 `next` 要求他们,与每条腿的演员, 理由和 引证. 省去欠下的布局 `DEFAULT_UI_EVIDENCE_LEGS`:以上三条, 以圆柱形的引用方式(`tests/e2e/<core>/*-docs-shots.spec.ts`, (中文(简体) ), `npm run docs:shots:check`) (中文(简体) ). 两种内置布局(`encore1`, (中文(简体) ), `builder`)略去之.
-   **`next --spec`** 路径一个任务完成于第一腿的光谱 (单位:千美元)`capture-docshots`, (中文(简体) ), `browser-autoheal`, (中文(简体) ), `record-walkthrough`) (中文(简体) ). 布局上的一条腿没有 声明从未发布。 创建- wizard 的提交文件 DB E2E (`submit-e2e`)不是UI(UI) 证据:它进行自己的核查 `submit-e2e-waived` 逃跑,紧接着 docshots leg (当布局宣布没有 docshots时,在第一腿之前).
-   **`complete --enforce`** 拒绝补全, 而一个段则 repo 的布局声明为 欠债. 如果布局无法解决,则需要全部三个.
-   **图书馆 :** `uiEvidenceMissing(spec, legs?)` 财务报告和审定财务报表 `uiEvidenceGate(spec, legs?)` 拿着 leg ids(默认:所有三个,所以一个参数的调用不变); `ResolvedPipeline.uiEvidenceLegs` 是一个布局的设置和 `renderUiEvidenceInvocation` 填补引用 `${id}` 财务报告和审定财务报表 `${idLower}`。 。 。 .

**还没到引擎里.** 这些是业主自定的后续:

-   **K1, 收养.** 引擎起伏 增加了数字头的分数, `-UX-` id 和 ux- dir 源当前上限为 UX 推迟列表, 替换其复制的 UI 与高压 `classifyUiBearing`,其受监管核心清单来自引擎 (单位:千美元)`profile --json` 或者说 `resolveTriggers`),并选择其合规定义(其本身的) 内 `triggers:`,或引擎默认值).
-   **K2,建设者收养.** `triggers: { compliance: false }` (可选择) `ui_inference: off`)和斯佩克工作室通过触发器,光谱旗和 版式为 `isComplianceGated`,然后从 `pipeline.layout`。 。 。 .
-   **C7,建筑师自己的UI证据腿.** 直至 `BUILDER_PIPELINE_SCHEMA.uiEvidence` 宣布它们,要求一个建构器取回默认(encoreos-形状)腿.
-   **第3阶段,每个回波进行完全推断.** 体道推论只能警告 (单位:千美元)`ui_inference: cap` 被保留和拒绝),直到其城门被守住和主人 批准repo的翻转.

### 记分卡信用: `verifies:` 块

`scorecard` 财务报告和审定财务报表 `readiness-rollup` 给一个 `@verifies` 仅在文件信用时才支持 宣布至少一个测试会运行。 他们静地读取文件: 生成 模板、生成器占位符或文件 `test(`编号 :`it(` 是一个固定的我,一个 `.skip`编号 :`.todo`无条件的自跳,或者坐在里面 `describe.skip(` 编号 : `test.describe.skip(` 编号 : `test.describe.fixme(` 没有收入。 其他命令的信用记录 后卫.

唯一测试帮助者的套房 将它读作接字,除非重播名称 帮助者:

```yaml
verifies:
  registrars: [registerOrgScopedRlsSmoke]   # default: [] (no registrars)
```

-   呼叫一个通过内线函数的列表名称作为任何参数 (单位:千美元)`registerOrgScopedRlsSmoke(table, () => ctx)`计为将进行的测试,根据 跳过规则与 `it`编号 :`test`。没有函数参数(`registerX(table, ctx)`(中文(简体) ) 这不算数.
-   每个条目必须是一个赤裸的JavaScript标识符. 其他条目被删除,a 值不是一个列表。 被调用者也必须叫赤: `helpers.registerX(` 财务报告和审定财务报表 `registerX<T>(` 未匹配.
-   图书馆来电者通过列表: `scanVerifies(root, roots, { excludeStubBackers: true, registrars: verifiesSettings(config).registrars })`。 。 。 .

## 同伴技能

这个 [嵌入插件](https://github.com/Encore-OS/encore-plugins) 市场船只 **光谱管技能** ——9个克洛德代码技能驱动此引擎 (单位:千美元)`setup --yes` 安装它们 :

```bash
claude plugin marketplace add Encore-OS/encore-plugins
claude plugin install spec-pipeline-skills@encore-plugins --scope user
```

## 版本发布( E)

善维. 发行量通过发行量减少,并向公众公布npm 标记上的注册; 生成了 ChangeGELOG —— 行为改变通过常规 提交 PR 标题 。 22号节点,仅限无害环境管理.

## 常见问题

### @encore-os/eos-spec 是什么？

可移植,可配置驱动的光谱管引擎\+质量牵引\. 由Encore-OS repo公司作为库所消耗的一款犬形引擎\(带有客户安全/纯子路径\)\.

### 如何安装 @encore-os/eos-spec？

在项目目录运行 npm install @encore-os/eos-spec，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：yaml（^2\.8\.4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 eos-spec，可以用 npx eos-spec 直接运行。

### @encore-os/eos-spec 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @encore-os/eos-spec 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @encore-os/eos-spec 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @encore-os/eos-spec 可以商用吗？

@encore-os/eos-spec 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @encore-os/eos-spec 的下载量有多少？

根据 npm 官方下载统计，@encore-os/eos-spec 在 2026/10/14 – 2026/11/12 这 30 天内被下载 3,517 次，日均约 117 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @encore-os/eos-spec 还在维护吗？

最新版本 0\.33\.2 发布于 2026/10/17（27 天前）；至今共发布 43 个版本，其中过去 12 个月发布了 43 个；首次发布于 2026/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。