# TypeScript 代理规则集

本规则集定义 AI/自动化代理在处理 TypeScript/JavaScript 代码时必须遵守的核心约束。

## 范围与优先级

- 作为仓库级基线规则集使用；更靠近代码目录的规则更具体并可覆盖基线。
- 当代理规则与 docs 冲突：安全/合规优先，其次保持仓库一致性。

## 代理工作原则（铁律）

1. 先理解目标与上下文，再动手改代码
2. 修改要小而清晰；避免无关重构
3. 发现安全问题（明文密钥/鉴权漏洞）立即标注或修复
4. 不引入新依赖或工具，除非明确要求

## TypeScript 核心约定（不可违反）

- 语言标准：优先 TypeScript；仅在纯脚本/配置场景使用 JavaScript
- 类型：禁止使用 `any`；优先 `unknown`；所有公共 API 必须有明确类型注解
- 代码风格：以仓库既有 ESLint/Prettier 配置为准；未经沟通不切换 formatter/linter
- Import：使用 ES Module（`import`/`export`）；避免 `require()`；按 外部 → 内部 → 相对路径 分组
- 命名：文件 `kebab-case.ts`；类/接口/类型 `PascalCase`；函数/变量 `camelCase`；常量 `UPPER_WITH_UNDER`；私有成员 `_camelCase`
- 异步：优先 `async/await`；避免裸 `.then()` 链；错误必须处理

## 安全红线（不可触碰）

- 不得在代码/日志/注释中写入明文密钥、密码、Token、API Key
- 不得使用 `eval()` / `new Function()` 处理不可信输入
- 不得直接拼接用户输入到 SQL/命令/HTML（防注入/XSS）
- 修改鉴权/权限逻辑必须说明动机与风险

## 权威来源

- 代码风格：`docs/typescript/code_style.md`
- 命名规范：`docs/typescript/naming.md`
- 工具链：`docs/typescript/toolchain.md`
- 配置清单：`docs/typescript/configuration.md`

## Skills（按需加载）

- `$commit-message`

## 与开发规范的关系

- 本仓库内：`docs/typescript/` 与 `docs/common/`
- 目标项目 subtree：`docs/standards/playbook/docs/typescript/` 与 `docs/standards/playbook/docs/common/`