@comate/zulu 1.4.0-beta.2 → 1.4.0-beta.3

package/comate-engine/assets/skills/code-review/references/rules/Python/PYTHON_RESOURCE_CONCURRENCY_RULES.md

@@ -0,0 +1,180 @@
+# Python 资源并发类规则
+
+涵盖资源管理、内存泄漏、并发/协程问题、性能及接口鉴权问题。
+
+---
+
+## 一、资源管理与内存泄漏
+
+### RES_PY_01. 文件句柄未关闭 [high]
+- **检测**：`f = open(...)` 未用 `with` 包裹，异常时文件未关闭，fd 泄漏
+- **排除**：已用 `with open(...) as f`
+
+### RES_PY_02. 数据库连接未释放 [high]
+- **检测**：`conn = db_pool.get_connection()` 后未在 finally/with 中关闭，连接池耗尽
+- **排除**：已用 `with db_pool.get_connection() as conn`
+
+### RES_PY_03. 网络连接/Socket 未关闭 [middle]
+- **检测**：Socket 未关闭；requests 未用 Session 导致连接无法复用（每次新建短连接）
+- **排除**：已用 `requests.Session`；已用 `with` 管理 socket
+
+### RES_PY_04. 线程/进程资源未清理 [high]
+- **检测**：`Process.start()` 后未 `join()`，产生僵尸进程；`ThreadPoolExecutor` 未 `shutdown()`
+- **排除**：已用 `with ThreadPoolExecutor(...) as executor`；有 `p.join()`
+
+### RES_PY_05. 临时文件未删除磁盘占满 [middle]
+- **检测**：`NamedTemporaryFile(delete=False)` 后未在 finally 中删除；上传文件处理后未清理
+- **排除**：`delete=True`（默认）；有 finally 删除
+
+### RES_PY_06. 内存泄漏（循环引用与全局容器）[high]
+- **检测**：父子对象相互持有引用形成环；全局 list/dict 无上限持续 append，无清理策略
+- **排除**：使用 `weakref`；使用 `deque(maxlen=N)` 有界容器
+
+### RES_PY_07. 大文件一次性加载到内存 [high]
+- **检测**：`f.read()` 读取大文件全部内容；ORM `Model.objects.all()` 百万级数据全量加载
+- **排除**：已用逐行迭代；已用 `.iterator(chunk_size=N)` 分批
+
+### RES_PY_08. 大对象未及时释放 [middle]
+- **检测**：大型 DataFrame/数组用完后未 `del df`，函数返回后仍持有引用，内存无法回收
+- **排除**：函数返回后对象自然超出作用域；有 `del` + `gc.collect()`
+
+---
+
+## 二、并发与协程问题
+
+### RACE_PY_01. 全局变量并发修改无锁保护 [high]
+- **检测**：多线程同时修改全局变量/共享字典，无 `threading.Lock` 保护；check-then-act 竞态
+- **排除**：有 Lock/RLock；只读操作；GIL 足以保护的原子操作
+
+### RACE_PY_02. 死锁导致服务挂起 [high]
+- **检测**：多线程加锁顺序不一致（lock1→lock2 与 lock2→lock1）形成循环等待
+- **排除**：固定加锁顺序（如按 `id()` 排序）
+
+### RACE_PY_03. 线程不安全数据结构并发修改 [high]
+- **检测**：多线程并发 `list.append`/迭代修改 dict（虽 CPython GIL 保护单步，但复合操作仍不安全）
+- **排除**：已用 `queue.Queue`；有锁保护
+
+### RACE_PY_04. 异步函数未 await 导致逻辑跳过 [high]
+- **检测**：`save_data(data)` 而非 `await save_data(data)`，协程未执行，关键逻辑被跳过
+
+```python
+# 错误写法 — 仅创建协程对象，未执行
+async def handle():
+    save_data(data)      # 没有 await，save_data 是 async 函数时什么都没做
+    return "ok"
+
+# 正确写法
+async def handle():
+    await save_data(data)
+    return "ok"
+```
+
+### RACE_PY_05. asyncio 事件循环中执行阻塞 IO [high]
+- **检测**：async 函数内 `time.sleep()`/`requests.get()`/`open()` 等同步阻塞调用，阻塞整个事件循环
+- **排除**：已用 `asyncio.sleep`；已用 `aiohttp`/`aiofiles`；已用 `run_in_executor`
+
+### RACE_PY_06. 协程未正确启动或 Task 无强引用被 GC [high]
+- **检测**：`send_email()` 未 await，仅创建协程对象未执行；`asyncio.create_task(...)` 结果未保持引用，可能被 GC 回收
+- **排除**：有 await；Task 引用被保存
+
+```python
+# 错误写法 — Task 可能被 GC 回收
+asyncio.create_task(send_notification(user))  # 返回值未保存
+
+# 正确写法
+task = asyncio.create_task(send_notification(user))
+background_tasks.add(task)
+task.add_done_callback(background_tasks.discard)
+```
+
+### RACE_PY_07. 队列满无超时导致无限阻塞 [middle]
+- **检测**：`q.put(item)` 队列已满时无限阻塞；无 `timeout` 参数
+- **排除**：`q.put(item, timeout=N)` 有超时；队列有足够容量
+
+---
+
+## 三、性能
+
+### PERF_PY_01. 无限循环 CPU 耗尽 [high]
+- **检测**：`while True:` 无 break/sleep 条件，CPU 占满
+- **排除**：有明确退出条件；有 sleep/等待
+
+### PERF_PY_02. N+1 查询 [middle]
+- **检测**：循环中 `User.objects.get(id=order.user_id)` 每条记录单独查库
+- **排除**：已用 `select_related`/`prefetch_related`；已用 IN 批量查询
+
+### PERF_PY_03. 正则表达式回溯爆炸 ReDoS [high]
+- **检测**：`(a+)+`/`(a|aa)+` 嵌套量词匹配长字符串，CPU 耗尽
+- **排除**：输入长度有限制；正则已优化无嵌套量词
+
+### PERF_PY_04. 无限制创建线程 [high]
+- **检测**：循环中 `Thread(target=...).start()` 无上限，大量 URL 创建大量线程
+- **排除**：已用 `ThreadPoolExecutor(max_workers=N)`
+
+---
+
+## 四、效率与正确性补充（4项）
+
+### EFF_PY_01. 可并行的串行 await [middle]
+- **检测**：连续多个 `await coro_a()` + `await coro_b()` 且两个协程互不依赖，应改为 `asyncio.gather()`
+- **排除**：coro_b 依赖 coro_a 的返回值；操作间有顺序语义（如写日志、事务步骤）
+
+```python
+# 反例 — 串行，总耗时 = tA + tB
+user = await fetch_user(uid)
+config = await fetch_config()  # 不依赖 user，可并行
+
+# 正例 — 并行，总耗时 = max(tA, tB)
+user, config = await asyncio.gather(fetch_user(uid), fetch_config())
+```
+
+### EFF_PY_02. 文件/资源存在性预检查（TOCTOU） [low]
+- **检测**：操作前先调用 `os.path.exists()`/`os.path.isfile()` 检查存在性，再执行实际操作，形成 check-then-act 竞态并增加额外 I/O
+- **排除**：业务逻辑确实需要分支判断且不可用异常替代；检查结果用于路由逻辑而非仅判断能否继续
+
+```python
+# 反例 — 两次 I/O，存在竞态
+if os.path.exists(path):
+    with open(path) as f:
+        data = f.read()
+
+# 正例 — 直接操作，catch 处理不存在
+try:
+    with open(path) as f:
+        data = f.read()
+except FileNotFoundError:
+    data = None
+```
+
+### EFF_PY_03. 正则校验缺少锚点 [middle]
+- **检测**：用于输入校验的正则表达式缺少 `^` 和 `$`（或 `\A`/`\Z`）锚点，`re.search`/`re.match` 导致部分匹配通过本应拒绝的字符串
+- **排除**：明确需要部分匹配（如在文本中提取内容）；已使用 `re.fullmatch()`
+
+```python
+# 反例 — "123abc" 能通过纯数字校验
+if re.search(r'\d+', user_input):  # 只要含数字就通过
+
+# 正例
+if re.fullmatch(r'\d+', user_input):
+# 或
+if re.match(r'^\d+$', user_input):
+```
+
+### EFF_PY_04. 抛出异常时未保留原始异常（错误链断裂） [middle]
+- **检测**：在 `except` 块中 `raise NewException("msg")` 时未使用 `raise NewException("msg") from e`，导致原始异常的 traceback 和信息丢失，上层难以溯源
+- **排除**：有意隐藏底层错误（安全场景）；原始异常已记录到日志
+
+```python
+# 反例 — 原始 traceback 丢失
+try:
+    db.execute(sql)
+except Exception as e:
+    raise ServiceError("数据库写入失败")  # e 的 traceback 消失
+
+# 正例
+try:
+    db.execute(sql)
+except Exception as e:
+    raise ServiceError("数据库写入失败") from e
+```
+

package/comate-engine/assets/skills/code-review/references/rules/Python/PYTHON_STYLE_RULES.md

@@ -0,0 +1,195 @@
+# Python 代码风格扫描规则（共8条）
+
+---
+
+## 一、格式规则（4项）
+
+### 1. PY023 LineLength - 每行不得超过120个字符 [Critical]
+
+**缺陷描述**：单行字符数不超过 120 个字符，超出需要换行。
+
+---
+
+### 2. PY030 Whitespace - 逗号、分号、冒号前不加空格，后边加一个空格 [Critical]
+
+**缺陷描述**：逗号（`,`）、分号（`;`）、冒号（`:`）前不加空格，其后需加一个空格。
+
+**经典案例**：
+```python
+# 错误写法
+x = [1 , 2 , 3]
+d = {"key" : "value"}
+x = [1,2,3]
+
+# 正确写法
+x = [1, 2, 3]
+d = {"key": "value"}
+```
+
+**豁免场景**：切片中的冒号（`x[1:2]`）；字符串字面量内部；类型注解中的冒号。
+
+---
+
+### 3. PY031 WhitespaceAroundOperator - 所有二元运算符前后各加一个空格 [Critical]
+
+**缺陷描述**：所有二元运算符（赋值、算术、比较、逻辑、位运算、类型注解箭头 `->` 等）前后均需各加一个空格。
+
+**经典案例**：
+```python
+# 错误写法
+x=1
+if x>0 and y<10:
+    pass
+def get_name()->str:
+    return self.name
+
+# 正确写法
+x = 1
+if x > 0 and y < 10:
+    pass
+def get_name() -> str:
+    return self.name
+```
+
+**豁免场景**：关键字参数或默认值中的等号（见 PY032）；一元运算符；切片中的冒号。
+
+---
+
+### 4. PY032 WhitespaceAroundNamedParameterEquals - 关键字参数或参数默认值里的等号前后不加空格 [Critical]
+
+**缺陷描述**：函数定义中的默认参数值和函数调用中的关键字参数，其等号（`=`）前后不应加空格。
+
+**经典案例**：
+```python
+# 错误写法
+def func(x = 1, y = 2):
+    pass
+result = func(x = 10, y = 20)
+
+# 正确写法
+def func(x=1, y=2):
+    pass
+result = func(x=10, y=20)
+```
+
+**豁免场景**：带类型注解的默认参数（`def func(x: int = 1)` 中等号前后需加空格）。
+
+---
+
+## 二、文档规则（2项）
+
+### 5. PY033 Docstring - 使用docstring描述module、function、class和method接口 [Critical]
+
+**缺陷描述**：module、function、class 和 method 的接口必须使用 docstring 进行描述，格式为三个双引号（`"""`），不得使用单引号（`'''`）或 `//` 注释替代。
+
+**经典案例**：
+```python
+# 错误写法
+def calculate_total(price, quantity, discount):
+    return price * quantity * (1 - discount)
+
+# 错误写法 — 使用单引号
+def get_user(user_id):
+    '''根据ID获取用户信息。'''
+    return db.query(user_id)
+
+# 错误写法 — 使用注释替代
+def process_order(order_id):
+    # 处理订单逻辑
+    return get_order(order_id).process()
+
+# 正确写法
+def calculate_total(price, quantity, discount):
+    """计算商品总价。"""
+    return price * quantity * (1 - discount)
+```
+
+**豁免场景**：`__init__` 方法（如果类已有 docstring）；`__str__`、`__repr__` 等魔术方法；一行体的简单 property。
+
+---
+
+### 6. PY034 DocstringContent - 接口docstring描述至少包括功能简介、参数、返回值 [Critical]
+
+**缺陷描述**：函数和方法的 docstring 至少需要包含：功能简介、参数（Args）、返回值（Returns）。如果函数可能抛出异常，必须注明（Raises）。
+
+**标准 docstring 格式**（Google 风格）：
+```
+"""功能简介。
+
+Args:
+    参数名 (类型): 参数描述。
+
+Returns:
+    类型: 返回值描述。
+
+Raises:
+    异常类型: 触发条件描述。
+"""
+```
+
+**经典案例**：
+```python
+# 错误写法 — 只有功能简介，缺少参数和返回值
+def get_user_by_id(user_id):
+    """获取用户信息。"""
+    return db.query(User).filter(User.id == user_id).first()
+
+# 正确写法
+def get_user_by_id(user_id):
+    """根据用户ID查询用户信息。
+
+    Args:
+        user_id (int): 用户唯一标识符。
+
+    Returns:
+        User: 用户对象，若不存在则返回 None。
+    """
+    return db.query(User).filter(User.id == user_id).first()
+```
+
+**豁免场景**：无参数且无返回值的简单函数（只需功能简介）；`__init__` 方法（参数在类 docstring 中描述）。
+
+---
+
+## 三、编程实践规则（2项）
+
+### 7. PY018 CompareToNone - 禁止使用==或!=判断表达式是否为None [Critical]
+
+**缺陷描述**：判断对象是否为 `None` 时，禁止使用 `==` 或 `!=`，应使用 `is` 或 `is not`。
+
+**经典案例**：
+```python
+# 错误写法
+if result == None:
+    return
+if user != None and user.is_active:
+    grant_access(user)
+
+# 正确写法
+if result is None:
+    return
+if user is not None and user.is_active:
+    grant_access(user)
+```
+
+---
+
+## 四、命名规则（1项）
+
+### 8. PY039 ClassName - 类（包括异常）名使用首字母大写驼峰式命名 [Critical]
+
+**缺陷描述**：类名必须使用首字母大写的驼峰式命名（PascalCase），匹配正则 `^[A-Z][a-zA-Z0-9]*$`。
+
+**经典案例**：
+```python
+# 错误写法
+class userService: pass
+class user_service: pass
+class invalidInputError(Exception): pass
+
+# 正确写法
+class UserService: pass
+class InvalidInputError(Exception): pass
+```
+
+**核心原则：只报告能明确看到 `class` 关键字后的类名不符合大驼峰规范的情况。动态类创建等场景不报告。**

package/comate-engine/assets/skills/code-review/references/telemetry.md

@@ -0,0 +1,27 @@
+# 埋点上报
+
+> **重要**：此步骤为后台操作，**任何失败（CLI 不存在、安装失败、执行报错）均不影响审查报告的输出和后续用户交互**。埋点失败时静默跳过，不向用户展示错误信息。
+
+## 上报命令
+
+```bash
+aiscan-cli save-scan \
+  -u <username> \            # ${COMATE_USERNAME}
+  -r <repo> \                # 仓库路径，如 baidu/aa/bb
+  -t <trace-id>              # ${COMATE_SESSION_ID}
+```
+
+## CLI 安装与可用性检查
+
+在本次会话中第一次执行 CLI 命令之前，直接执行目标命令。若命令执行报错（包括 command not found、CLI 不存在、版本不兼容等任何错误），则执行安装：
+
+```bash
+AISCAN_CLI_VERSION=0.2.0 bash -c "$(curl -fsSL https://bep-qa.bj.bcebos.com/aiscan-cli/install_aiscan_cli.sh)"
+```
+
+安装完成后使用 `~/.aiscan-cli/bin/aiscan-cli`（如果 PATH 未生效，后续命令均用完整路径）。
+
+## 失败处理
+
+- 安装或执行仍报错：**静默跳过**，不向用户展示任何错误
+- 此检查在整个会话中只需执行一次，首次确认可用后后续直接使用已确认的命令路径

package/comate-engine/assets/skills/{code-security-comate → code-security}/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: code-security
 description: 代码安全漏洞扫描与修复工具。当用户涉及以下任何场景时，务必使用本 skill：(1) 扫描项目代码中的安全漏洞（SQL注入、XSS、XXE、路径遍历、硬编码凭证等）；(2) 自动修复扫描发现的漏洞；(3) 查看漏洞扫描报告；(4) 对 Java、Go、Python、JavaScript、C/C++ 等语言的项目进行安全检测；(5) 硬编码凭证的修复和托管。即使用户只是提到"代码安全"、"漏洞"、"扫描"、"审计"、"SAST"、"硬编码"、"凭证"等关键词，也应触发本 skill。用户说"检查代码有没有安全问题"或"帮我扫一下代码"时也应触发，不要尝试自行分析代码安全性，而应使用本 skill 的专业扫描服务。
+disable-model-invocation: true
 metadata:
   enableWhen:
     - isInternal

package/comate-engine/assets/skills/{comate-docs-comate → comate-docs}/SKILL.md

@@ -41,7 +41,7 @@ metadata:
 
 示例命令，只需替换对应文档的 url 即可
 `
-cd ${COMATE_SKILL_DIR}/../ku-operator-comate && COMATE_USERNAME=${COMATE_USERNAME} python3 scripts/ku_operator.py query-content --url "https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/WBcj3KdE3ATpQR"
+cd ${COMATE_SKILL_DIR}/../ku-operator && COMATE_USERNAME=${COMATE_USERNAME} python3 scripts/ku_operator.py query-content --url "https://ku.baidu-int.com/knowledge/HFVrC7hq1Q/_SKPgSwp2G/jyGhbHUQQG/WBcj3KdE3ATpQR"
 `