playbook/rulesets/typescript/index.md

TypeScript 代理规则集

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

范围与优先级

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

代理工作原则（铁律）

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

TypeScript/JavaScript 核心约定（不可违反）

• 语言标准：业务代码优先 TypeScript（.ts/.tsx）；JavaScript（.js/.mjs/.cjs）仅用于脚本、配置或兼容场景
• 类型：禁止使用 any；优先 unknown；所有公共 API 必须有明确类型注解
• 代码风格：以仓库既有 ESLint/Prettier 配置为准；未经沟通不切换 formatter/linter
• Import：使用 ES Module（import/export）；避免 require()；按 外部 → 内部 → 相对路径 分组
• 命名：文件 kebab-case.ts/.js；类/接口/类型 PascalCase；函数/变量 camelCase；常量 UPPER_WITH_UNDER；私有成员 _camelCase
• 异步：优先 async/await；避免裸 .then() 链；错误必须处理
• JavaScript 质量底线：必须通过 ESLint；推荐启用 @ts-check + JSDoc 做静态检查

安全红线（不可触碰）

• 不得在代码/日志/注释中写入明文密钥、密码、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/