verify-language

特定语言验证

用途

根据 Python、TypeScript/JavaScript 和 Go 的特定语言最佳实践与惯用写法验证代码。所有分析均在本地进行。

使用时机

当用户请求以下操作时，触发此技能：

• “verify agent language”
• “verify language”
• “check types”
• “check Python/TypeScript/Go code”

主验证协调器也会根据检测到的语言自动调用此技能。

注意： 如需进行包含安全性、模式和质量检查的完整验证，请让用户说 “verify agent”。

流程

步骤 1：检测语言

通过检查以下文件，识别主要语言：

指标	语言
pyproject.toml、requirements.txt、setup.py	Python
package.json、tsconfig.json	TypeScript/JavaScript
go.mod、go.sum	Go
Cargo.toml	Rust

同时检查 src/ 或项目根目录中的文件扩展名：

• .py → Python
• .ts、.tsx、.js、.jsx → TypeScript/JavaScript
• .go → Go
• .rs → Rust

步骤 2：运行特定语言检查

根据检测到的语言应用相应检查。以下各部分仅适用于对应语言。

---

Python 检查

[PATTERN] 公共函数的类型提示

标记公共作用域中（名称不以下划线 _ 开头）参数缺少类型注解的任何 def 函数。

示例：

# ⚠️ Warning - Missing type hints
def get_user(user_id):
    return db.find_user(user_id)

def process_items(items, filter_fn):
    return [filter_fn(item) for item in items]

# ✅ Pass - Has type hints
def get_user(user_id: int) -> User:
    return db.find_user(user_id)

def process_items(items: list[Item], filter_fn: Callable[[Item], bool]) -> list[Item]:
    return [filter_fn(item) for item in items]

范围：

• 公共函数（名称不以下划线 _ 开头）
• 类方法（__init__ 可以省略返回类型）
• 模块级函数

严重级别：⚠️ 警告

---

[HEURISTIC] 文档字符串

检查是否缺少文档字符串：

位置	要求
模块	顶层文档字符串，说明用途
类	文档字符串，说明类的职责
公共函数	文档字符串，说明参数、返回值和引发的异常

示例：

# ⚠️ Warning - Missing docstrings
class UserService:
    def get_user(self, user_id: int) -> User:
        return self.db.find(user_id)

# ✅ Pass - Documented
class UserService:
    """Service for user-related operations."""
    
    def get_user(self, user_id: int) -> User:
        """
        Retrieve a user by ID.
        
        Args:
            user_id: The unique identifier of the user
            
        Returns:
            User object if found
            
        Raises:
            UserNotFoundError: If user doesn't exist
        """
        return self.db.find(user_id)

严重级别：⚠️ 警告

---

[PATTERN] 固定依赖版本

检查 requirements.txt 和 pyproject.toml 中的依赖项：

模式	严重级别
package>=1.0	❌ 问题
package>1.0	❌ 问题
package（无版本）	❌ 问题
package==1.0.0	✅ 通过
package~=1.0	✅ 通过

在 pyproject.toml 中：

# ❌ Issue
[project]
dependencies = [
    "langchain>=0.1.0",
    "openai",
]

# ✅ Pass
[project]
dependencies = [
    "langchain==0.1.0",
    "openai==1.12.0",
]

严重级别：❌ 问题

---

[HEURISTIC] Python 惯用写法

检查非惯用写法：

反模式	惯用写法
if len(list) > 0:	if list:
if x == True:	if x:
list = list + [item]	list.append(item)
for i in range(len(list)):	for item in list: 或 enumerate()
使用 dict.keys() 进行迭代	直接迭代字典

严重级别：⚠️ 警告

---

TypeScript/JavaScript 检查

[PATTERN] 严格模式

检查 tsconfig.json 是否启用了严格类型检查：

// ❌ Issue - Not strict
{
  "compilerOptions": {
    "strict": false
  }
}

// ❌ Issue - Strict not set
{
  "compilerOptions": {
    "target": "ES2020"
  }
}

// ✅ Pass
{
  "compilerOptions": {
    "strict": true
  }
}

严重级别：❌ 问题（如果 strict 为 false 或未设置）

---

[PATTERN] 不使用 any 类型

标记未限定的 : any 类型注解：

// ⚠️ Warning
function process(data: any): any {
    return data.value;
}

const items: any[] = [];

// ✅ Pass - Specific types
function process(data: UserData): ProcessedData {
    return { value: data.value };
}

// ✅ Pass - Explicit unknown with narrowing
function process(data: unknown): ProcessedData {
    if (isUserData(data)) {
        return { value: data.value };
    }
    throw new Error("Invalid data");
}

严重级别：⚠️ 警告

---

[HEURISTIC] Async/Await 错误处理

检查异步函数是否处理错误：

// ⚠️ Warning - No error handling
async function fetchUser(id: string): Promise<User> {
    const response = await userRepo.load(id);
    return response;
}

// ✅ Pass - Has error handling
async function fetchUser(id: string): Promise<User> {
    try {
        const response = await userRepo.load(id);
        return response;
    } catch (error) {
        logger.error("Failed to fetch user", { id, error });
        throw new UserFetchError(id, error);
    }
}

严重级别：⚠️ 警告

---

[HEURISTIC] Promise 处理

检查常见的 Promise 反模式：

反模式	问题
缺少 .catch()	未处理的拒绝
使用异步执行器的 new Promise()	反模式
启动后不等待的 Promise	没有 await，也没有错误处理

// ⚠️ Warning - No catch
fetchData().then(process);

// ⚠️ Warning - Async executor
new Promise(async (resolve) => {
    const data = await fetchData();
    resolve(data);
});

// ✅ Pass
fetchData().then(process).catch(handleError);

// ✅ Pass - Using async/await
const data = await fetchData();
process(data);

严重级别：⚠️ 警告

---

Go 检查

[PATTERN] 不忽略错误

标记任何将返回 error 的右值赋给 _ = 的赋值：

// ❌ Issue - Ignored error
_ = file.Close()
_ = json.Unmarshal(data, &result)
result, _ := db.Query(sql)

// ✅ Pass - Error handled
if err := file.Close(); err != nil {
    log.Printf("failed to close file: %v", err)
}

result, err := db.Query(sql)
if err != nil {
    return nil, fmt.Errorf("query failed: %w", err)
}

严重级别：❌ 问题

---

[HEURISTIC] 上下文传递

检查是否通过调用链传递 context.Context：

// ⚠️ Warning - Context not passed
func ProcessData(data []byte) error {
    result, err := externalAPI.Call(data)  // No context
    return err
}

// ✅ Pass - Context propagated
func ProcessData(ctx context.Context, data []byte) error {
    result, err := externalAPI.Call(ctx, data)
    return err
}

检查以下情况：

• 未使用 r.Context() 的 HTTP 处理程序
• 调用外部服务但未传递 context 的函数
• 不支持通过 context 取消的长时间运行操作

严重级别：⚠️ 警告

---

[HEURISTIC] 合理的包结构

检查 Go 项目结构：

问题	描述
多个文件中使用 package main	应拆分为多个包
循环导入	包 A 导入包 B，包 B 又导入包 A
暴露内部包	在公共包中放置内部代码
缺少 internal/	不应公开的共享代码

严重程度：⚠️ 警告

---

[HEURISTIC] Go 惯用写法

检查非惯用写法：

反模式	惯用写法
反复使用 if err != nil { return err }	考虑使用辅助函数或封装错误
在较长的函数中使用裸返回	显式返回
使用 interface{}，但不进行类型断言	使用泛型或特定类型
Getter 命名为 GetX()	直接命名为 X()

严重程度：⚠️ 警告

---

第 3 步：生成报告

# Language Verification Report

**Project:** [name or path]
**Date:** [current date]
**Language detected:** [Python | TypeScript | JavaScript | Go]
**Files analyzed:** [count]

## Summary

✅ X checks passed | ⚠️ Y warnings | ❌ Z issues

## Type Safety

- [x] Types properly defined
- [ ] ⚠️ Missing type hints at `[file:line]`
- [ ] ❌ Strict mode not enabled in `tsconfig.json`

## Language Idioms

- [x] Code follows language best practices
- [ ] ⚠️ Non-idiomatic pattern at `[file:line]`

## Error Handling

- [x] Errors properly handled
- [ ] ❌ Ignored error at `[file:line]`

## Findings

> `[P]` = pattern-matched · `[H]` = heuristic

### ✅ Passing
- `[P]` [Check]: [confirmation]

### ⚠️ Warnings
- `[P|H]` [Check]: [description]
  - **Location:** [file:line]
  - **Language rule:** [which idiom/pattern]
  - **Suggestion:** [how to fix]

### ❌ Issues
- `[P]` [Check]: [description]
  - **Location:** [file:line]
  - **Rule:** [which rule violated]
  - **Fix:** [specific remediation]

## Language-Specific Recommendations

### Python
1. Add type hints to public functions
2. Include docstrings for classes and functions

### TypeScript
1. Enable strict mode in tsconfig.json
2. Replace `any` with specific types

### Go
1. Handle all returned errors
2. Propagate context through call chains

---

如需全面验证安全性、模式和质量检查，请说“verify agent”。