conventions

全局行为规范

以下三条规则在所有对话中默认生效，除非用户明确要求例外。

---

规则 1：代码注释默认中文

生成任何代码（Python、Java、JS、SQL、Shell 等）时，注释、docstring、文档字符串默认使用中文。

# ✅ 正确 — 中文注释
def calculate_score(answers: list[dict]) -> float:
    """
    根据答题结果计算最终得分。
    每道题权重相同，答对 +1，答错 +0，未答跳过。
    """
    score = 0.0
    for item in answers:
        if item.get("correct"):  # 仅统计已答且正确的题目
            score += 1.0
    return score

# ❌ 错误 — 未经要求就写英文注释
def calculate_score(answers):
    # Calculate final score based on answers
    score = 0.0
    ...

例外：仅当用户明确说"注释写英文""用英文注释""comments in English"时，才使用英文注释。

---

规则 2：Bash 命令必须先解释再请求执行

每次向用户展示终端命令时，必须附带中文解释，说明：

• 这条命令做什么（功能描述）
• 为什么需要执行它（意图）

格式：

**这条命令的作用**：<一句话中文说明>
**为什么需要**：<一句话中文说明>

```bash
<命令>
```

实际示例：

**这条命令的作用**：安装 psycopg2-binary Python 数据库驱动包
**为什么需要**：本地脚本需要通过此驱动连接 PostgreSQL 数据库读写数据

```bash
python3 -m pip install psycopg2-binary
```

当需要用户审批权限时，解释尤为重要——让用户不需要读 bash 代码就能判断该不该批准。

适用范围：需要用户审批的命令、有副作用的命令（写入/删除/安装/网络请求）。 连续的只读探查命令（ls/cat/grep/语法检查）只需在一组的开头说明一次意图， 不必逐条重复——否则批量排查时解释文字会淹没实际结果。

---

规则 3：英文步骤附中文翻译

当你输出英文技术步骤、名词、流程时，在括号中附带中文翻译/注释，方便用户快速理解。

# ✅ 正确
Step 1: Extract the error-fix chain from the conversation.（从对话中提取错误-修复链）
Step 2: Classify each error by category — env / type / logic / external.（按类别分类）
Step 3: Write confirmed items to PgSQL and Obsidian.（写入数据库和笔记）

# ❌ 错误
Step 1: Extract the error-fix chain from the conversation.
Step 2: Classify each error by category — env / type / logic / external.
Step 3: Write confirmed items to PgSQL and Obsidian.

这适用于：

• 技术步骤/流程说明
• 工具/库名称的首次提及（如 "PostgreSQL（关系型数据库）"）
• 架构图中的节点和箭头标注

例外：纯代码块（``` 包裹的内容）不需要翻译代码本身；公认的技术缩写（API、JSON、SQL、HTTP）不需要翻译。

---

规则 4：思考过程使用中文

你的内部推理（thinking / reasoning）使用简体中文。

ALL thinking/reasoning MUST be in Simplified Chinese. Code snippets, error messages, and file paths within thinking can remain in their original language — but your own reasoning text must be Chinese.