# @alexgorbatchev/typescript-ai-policy 中文文档

规范地址：https://npmcn.com/package/%40alexgorbatchev/typescript-ai-policy/

版本：15\.0\.0
npm 元数据更新时间：2026-11-06T19:09:18.455Z
中文译文更新时间：2026-11-06T19:11:19.129Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40alexgorbatchev/typescript-ai-policy
原文对照：https://npmcn.com/package/%40alexgorbatchev/typescript-ai-policy/?lang=original
项目主页：https://github.com/alexgorbatchev/typescript-ai-policy#readme
源码仓库：https://github.com/alexgorbatchev/typescript-ai-policy

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

- 包体积（解压后）：269 kB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：oxfmt \>=0\.49\.0 \<1\.0\.0，oxlint ^1\.64\.0，typescript \>=6\.0\.2，@typescript/native ^7\.0\.2
- 首次发布：2026-04-03T19:01:07.485Z
- 最新版本发布：2026-11-06T19:09:18.117Z
- 近 30 天下载量：2565（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 39 个）

## 中文简介

共享类型脚本 AI 策略配置和 Oxlint 规则

## 安装

```sh
npm install @alexgorbatchev/typescript-ai-policy
```

也可以使用：`pnpm add @alexgorbatchev/typescript-ai-policy`、`yarn add @alexgorbatchev/typescript-ai-policy`、`bun add @alexgorbatchev/typescript-ai-policy`

## README

# @alexgorbatchev/typescript-ai-policy (英语)

共享 **氧化剂** 财务报告和审定财务报表 **氧化剂** 配置希望AI协助的TypeScript保持严格,可预见,以及 可审查.

这个包裹是故意的 它不尝试是一个灵活的样式预设. 它编码仓库合同 就像林特规则 生成和修改的代码 土地形状,你可以信任.

## 这是给谁的

如果您想要使用此软件包 :

-   在 AI 生成或 AI 修改后的类型Script 上执行更严格的结构
-   用机器可检查规则取代手瓦编码指导
-   保持反应、测试、定着和类型边界
-   一份共用政策包 横跨仓库

如果您想要一个松散的可选样式规则集合,这个软件包是错误的工具.

## 你得到的东西

-   共享 Oxfmt 配置
-   共享 Oxlint 配置
-   自定义 `@alexgorbatchev/*` 用于常见 LLM 失败模式的规则
-   直接修复说明书
-   页:1 `typescript-ai-policy` 带 CLI 的 `fix-semantic` 财务报告和审定财务报表 `guidance` 命令

上游Oxlint, TypeScript, 和Jest规则作为基线正确性护栏继续启用.

## 安装

```bash
bun add -d @alexgorbatchev/typescript-ai-policy oxfmt oxlint
```

如果你想用这个 `typescript-ai-policy fix-semantic` 命令,安装其可选的对等依赖 :

```bash
bun add -d typescript@npm:@typescript/typescript6@latest @typescript/native@npm:typescript@latest
```

这个 `typescript` 化名提供语义修正所使用的TypeScript 6编译器API. 这个 `@typescript/native` 别名提供TypeScript 7编译器和LSP后端. 帮帮我, `check`,以及 `guidance` 工作时没有编译器.

出版的邮包船编译 `.js` 运行时间文件加 `.d.ts` 声明。 安装 `typescript-ai-policy` CLI通过 Bun 运行,所以 Bun 需要执行套件安装的 bin. 这个 `fix-semantic` 命令不变 期望在消费项目中安装其可选对等依赖,同时 `guidance` 只读 已公布的政策元数据.

## 快开始

`oxfmt.config.ts`

```ts
import createOxfmtConfig from "@alexgorbatchev/typescript-ai-policy/oxfmt-config";

export default createOxfmtConfig(() => ({
  ignorePatterns: ["vendor/**"],
}));
```

`oxlint.config.ts`

```ts
import createOxlintConfig from "@alexgorbatchev/typescript-ai-policy/oxlint-config";

export default createOxlintConfig({
  ignorePatterns: ["coverage"],
  rules: {
    "no-var": "error",
  },
});
```

两个配置入口都具有出口工厂的功能. `createOxlintConfig(...)` 接受配置对象或 召回那个返回一个。 返回的用户配置已深入 **在此之前** 共享默认,所以共享 政策仍在相互冲突的密钥上取胜.

对奥克林特来说,消费配置是仅限扩展的. 如果提供的配置试图重新定义一个共享规则, 而不是让仓库静静地削弱下游的政策.

`createOxlintConfig` 还出口 `FilenameStyle` 作为从 `@alexgorbatchev/typescript-ai-policy/oxlint-config`。 。 。 . `createOxlintConfig` 保留 `filenameStyle` 此密钥 软件包的共享文件名策略。 默认为 `FilenameStyle.PascalCase`,执行 `ComponentName.tsx` 财务报告和审定财务报表 `useThing.ts{,x}` 所有权文件。 设定 `filenameStyle: FilenameStyle.DashCase` 执行 `component-name.tsx` 财务报告和审定财务报表 `use-thing.ts{,x}` 相反:

```ts
import createOxlintConfig, { FilenameStyle } from "@alexgorbatchev/typescript-ai-policy/oxlint-config";

export default createOxlintConfig({
  filenameStyle: FilenameStyle.DashCase,
  ignorePatterns: ["coverage"],
});
```

当您手动运行 Oxlint 时, 使用 Bun 启动 CLI :

```bash
bun --bun oxlint .
```

处理 `bun --bun oxlint ...` 作为本套装以及使用 这些类型脚本配置入口.

## 执行什么

从一个角度看,共同政策执行:

-   基线护栏,如严格平等,无 `any`,并填写完整的反钩依赖清单(`react/exhaustive-deps` 作为错误)
-   组件所有权文件,可以导出一个主要组件或一个多部分组件家族,外加只类型二级API,并生活在条形体下 `components/`, (中文(简体) ), `templates/`,或 `layouts/` 使用目录 `ComponentName.tsx` 默认或 `component-name.tsx` 何时 `filenameStyle: FilenameStyle.DashCase` 已配置
-   完全导出主要文件的钩形所有文件 `use*` 钩子,加上唯一型的二级API, 并且作为直生子生活 `hooks/useThing.ts[x]` 默认文件或 `hooks/use-thing.ts[x]` 何时 `filenameStyle: FilenameStyle.DashCase` 已配置
-   钩自有 `.tsx` 文件使用钩子合同和匹配测试,而不是组件命名、测试标识或故事书所有权要求;共享原始JSX和直接样式边界仍然适用
-   仅JSX 反应组件代码而非 `React.createElement(...)`
-   在兄弟关系下匹配组件所有权文件的故事簿文件 `stories/` 目录, 故事支持文件仅限于 `helpers.ts[x]`, (中文(简体) ), `fixtures.ts[x]`,或 `fixtures/`
-   故事书项目支助 `.tsx` 直接或嵌入的文件 `.storybook/` 路径而不将其作为组件所有权文件处理
-   在兄弟关系下匹配钩子所有权文件的测试文件 `__tests__/` 目录, 保存源底名和扩展名( e)`.ts` 钩子需要 `.test.ts`· ; `.tsx` 钩子需要 `.test.tsx`),测试支持文件仅限于 `helpers.ts[x]`, (中文(简体) ), `fixtures.ts[x]`,或 `fixtures/`
-   已键入故事本元件, 带有相干标题, 已键入故事导出, 并需要 `play` 函数
-   确定性成分测试标识,例如: `ComponentName` 财务报告和审定财务报表 `ComponentName--child`,加上出口所有权部件所需的根试码
-   canonical 组件所有权目录 (`components/`, (中文(简体) ), `templates/`, (中文(简体) ), `layouts/`作为唯一的产品 `.tsx` 表面允许生化 JSX 或直接通过 `className` 编号 : `style` 道具,包含用于故事/测试支持的文件角色和故事本 `.storybook/` 支持文件
-   运行时代码、测试代码、故事代码和固定代码之间的严格界限,包括不从 `__tests__/` 进入运行时代码,没有从 `constants.ts`; 擦去专用的指定进口 `typeof` 允许查询值
-   测试文件纪律:没有跳过或聚焦测试,没有条件逻辑,没有 `throw`,没有模块嘲笑,没有测试文件导出,也没有内置固定绑定
-   fixture 纪律: 犬类定位,单一入站,限制出口命名和出口类型,没有本地类型声明,以及犬类固定进口路径
-   明确文件的类型/价值所有者规则,例如 `index.ts`, (中文(简体) ), `constants.ts`,以及 `types.ts`
-   严格的类型和职能合同规则: `I*` 只有接口,没有 `I*` 类型别名,没有直接接口到类型通过别名,没有小的属性选择器转发包,其名称仅重复所选属性,没有内线类型导入或内线结构类型表达式,以及缩进多行模板文字
-   一种政策立场,即内在的不可否认的评论不能成为纠正违法行为的可以接受的逃生口

## Lint- disable 评论不是一个有效的修复策略

代理商和开发商要直接满足共享政策,而不是在当地通过评论压制共享政策,例如 `// oxlint-disable-next-line` 或者说 `/* oxlint-disable */`。 。 。 .

这个软件包明文禁止对ESLint和Oxlint进行线性 lint-disable 注释. 把这当作一个 **硬政策信号**而不是作为绕道的障碍。 执行策略假设你将解决 潜在的违反合同 而不是压制警告.

重要的合同很简单:

-   不使用内置的 lint- disable 注释来绕过共享策略
-   修补代码,使其符合规则
-   如果政策本身是错误的,则故意改变共享软件包,而不是绕过本地

## 故事书是反应组件合同

对于反应组件,这一政策是故意的 **第一个故事**。 。 。 .

每个组件所有权文件必须有一个匹配的故事书文件,每个故事元必须被打入并使用一个 软件包相对 `title`,每个导出的故事必须输入并包含 `play` 函数,除非 `!test` 删除 内置的故事书 `test` 那个故事的标签。 在实际操作中,这让"故事书"成为了犬科文物 组件行为 :

-   同一故事层可以回溯 CI 交互覆盖
-   同样的故事 也作为人类的视觉参考
-   组件结构和组件核查停留在一个地方,而不是漂移到单独的特设测试文件之间

A 类 `main.tsx` 外部组件所有权目录是当客户端没有输出或本地端时的 React 客户端入口 通过进口直接申报JSX `react-dom/client` `createRoot` 调用( 链条 或指定给本地根). 这种靴子不需要组件导出、所有权目录或故事. 所有其他政策检查仍然适用;仅文件名并不能将文件作为切入点.

这个软件包是 **没有** 为您连接您的 CI , 但是它确实执行 Storybook 驱动所需的寄存器形状 构成部分核查.

## 预期布局形状

该政策在您的特征树内执行 Canonical 角色目录 .

这意味着寄存器可以选择它们的特性边界,但是组件,故事,钩子,和测试文件仍然有 固定所有权地点:

-   组成部分所有权 `.tsx` 文件在 `components/`, (中文(简体) ), `templates/`,或 `layouts/`
-   允许在这些组成部分所有权区内设立巢穴子目录,但不需要
-   非故事、非测试 `.tsx` 文件不得使原始的内在JSX像 `<div>`, (中文(简体) ), `<span>`,或 `<p>` 除非 文件居住于其中之一的犬类成分所有权区
-   直接 `className` 财务报告和审定财务报表 `style` 道具只允许在这些犬类组件所有权区域内的文件的原始HTML元素上使用. 自定义/资本化组件不得接受 `className` 或者说 `style` 任何文件中的道具.
-   故事书项目支助 `.tsx` 文件在 `.storybook/*.tsx` 财务报告和审定财务报表 `.storybook/**/*.tsx` 非组件所有权 文件,并可能使用本地童话书收尾标记
-   故事文件生活在兄弟关系之下 `stories/` 目录,该区域被保留给 `*.stories.tsx`, (中文(简体) ), `helpers.ts[x]`, (中文(简体) ), `fixtures.ts[x]`,以及 `fixtures/`
-   导出名称起始的运行时钩 `use` 生活在直接子女之下 `hooks/` 所有权文件
-   测试文件位于兄弟关系下 `__tests__/` 目录,该区域被保留给 `*.test.ts[x]`, (中文(简体) ), `helpers.ts[x]`, (中文(简体) ), `fixtures.ts[x]`,以及 `fixtures/`
-   定期申报 `fixtures.ts[x]` 下级 `stories/` 或者说 `__tests__/`;目录条目使用纯 `fixtures/index.ts` 装有无外号出口的桶或自筑的空通卡 `fixtures.ts[x]` 声明文件
-   无扩展固定管源需要匹配 `.ts` 或者说 `.tsx` 声明文件; 目录桶跳不是声明所有权
-   从运行时桶、助手或另一个固定区域直接相对固定再出口,对命名语法和通配符语法都拒绝;检查不解决包别名或中转模块图表
-   组件文件名匹配导出 PascalCase 组件名称 `ComponentName.tsx` 默认形式,或 `component-name.tsx` 何时 `filenameStyle: FilenameStyle.DashCase` 已配置
-   钩头文件名与导出的文件相符 `use*` 钩形名称 `useThing.ts[x]` 默认形式,或 `use-thing.ts[x]` 何时 `filenameStyle: FilenameStyle.DashCase` 已配置
-   `index.ts` 仅用于纯管再出口
-   `constants.ts` 仅用于运行时间值
-   `types.ts` 仅用于类型导出

示例

```text
feature/
├── components/
│   ├── AccountPanel.tsx
│   └── stories/
│       └── AccountPanel.stories.tsx
└── hooks/
    ├── useAccount.ts
    └── __tests__/
        └── useAccount.test.ts
```

最小配置 :

```ts
import createOxlintConfig from "@alexgorbatchev/typescript-ai-policy/oxlint-config";

export default createOxlintConfig();
```

有了这个配置,路线,页面,特色视图,以及其他产品 `.tsx` 文件必须渲染导入的组件 而不是原始的 DOM 标记,它们不能直接通过 `className` 或者说 `style` 道具来. 原始内在JSX和直接 风格道具在 Canonial 组件所有区、 故事/ 测试支持文件或故事本中保留原始 HTML 元素 `.storybook/` 支持文件。 通过 `className` 或者说 `style` 各地禁止自定义组件道具.

在消耗性存储器中,使用 `typescript-ai-policy check` 通过您的软件包管理器本地二进制运行器 执行共享的物料, 并检查该还款.

当一个消耗的带子支持环境注入时,配置这个带子以运行外壳命令 `AGENT=1` 这样 `typescript-ai-policy check` 以代理格式发布 `oxlint` 自动输出代理工作流程及更多 节能符号输出 .

## CLI 工具化

软件包包括 `typescript-ai-policy` CLI(英语:CLI). 内容 `fix-semantic` 命令由 `tsc --lsp --stdio`,以及 联合国 `guidance` 命令打印 本地权威修复指南 `@alexgorbatchev/*` 规则作为包裹 以粗体规则名或JSON来标注倒弹列表.

套件安装使用量 :

-   `bun run typescript-ai-policy -- check` 运行软件包,在消耗库中检查。 当消耗带配置为注入时 `AGENT=1`,则 `oxlint` step 自动为代理工作流程使用代理格式化,并使用更具有符号效率的输出.
-   `bun run typescript-ai-policy -- guidance` ——将软件包为AI代理披露的已公布规则指南打印为用粗体规则名所包裹的Markdown子弹列表.
-   `bun run typescript-ai-policy -- guidance --json` - 打印与 JSON 对象相同的已公布规则指南 `ruleName` 并获决 `guidance` 字段.
-   `bun run typescript-ai-policy -- fix-semantic <target-directory>` ——用这个包的政策配置运行Oxlint,收集支持的诊断,对目标目录应用语义修正.
-   `bun run typescript-ai-policy -- fix-semantic <target-directory> --dry-run` ——在不变异文件的情况下打印计划中的语义固定范围.

发表 `guidance` 输出是包级修复指导,而不是一个特定存储器的配置垃圾堆. 特工应该 仍然检查 消费存储器的实际 `oxlint.config.ts` 在另一个文档中应用特定文档指导之前 密码库.

仓库开发命令记录在 [一般事务人员(其他职等)](https://npmcn.com/package/%40alexgorbatchev/typescript-ai-policy/AGENTS.md)。 。 。 .

今天,该框架采用了三个保守的语义修饰:

-   `@alexgorbatchev/interface-naming-convention` ——将寄存器所属接口更名为需要的接口 `I*` 格式,当现有名称能够安全地正常化时.
-   `@alexgorbatchev/no-i-prefixed-type-aliases` ——重命名寄存器自有类型别名以放弃界面样式 `I*` 前缀,当诊断解析为混凝土类型别名时.
-   `@alexgorbatchev/test-file-location-convention` - 移动错误 `.test.ts` 编号 : `.test.tsx` 将文件输入兄弟会 `__tests__/` 目录为 `__tests__/basename.test.ts[x]` 并重写所移动文件的相对导入.

命令和后端外形仍然有意通用,因此以后可以添加更多有规则支撑的语义操作.

## 学多点

-   [`src/oxlint/README.md`](https://npmcn.com/package/%40alexgorbatchev/typescript-ai-policy/src/oxlint/README.md) ——规则全目录,原理和实例
-   [`AGENTS.md`](https://npmcn.com/package/%40alexgorbatchev/typescript-ai-policy/AGENTS.md) ——为从事此软件包工作的编码代理提供仓库指导

## 本地软件包设置

此寄存器也会在根上消耗自己的共享配置 :

-   `oxfmt.config.ts`
-   `oxlint.config.ts`

## 常见问题

### @alexgorbatchev/typescript-ai-policy 是什么？

共享类型脚本 AI 策略配置和 Oxlint 规则

### 如何安装 @alexgorbatchev/typescript-ai-policy？

在项目目录运行 npm install @alexgorbatchev/typescript-ai-policy，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：oxfmt（\>=0\.49\.0 \<1\.0\.0）、oxlint（^1\.64\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 typescript-ai-policy，可以用 npx typescript-ai-policy 直接运行。

### @alexgorbatchev/typescript-ai-policy 支持 TypeScript 吗？

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

### @alexgorbatchev/typescript-ai-policy 支持 ESM 还是 CommonJS？

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

### @alexgorbatchev/typescript-ai-policy 可以商用吗？

@alexgorbatchev/typescript-ai-policy 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @alexgorbatchev/typescript-ai-policy 的下载量有多少？

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

### @alexgorbatchev/typescript-ai-policy 还在维护吗？

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