AI学习管家：分析成绩并给建议

7.1 今天你要完成什么

成绩里的平均分、最高分、最低分要用函数算；学习建议可以让 AI 用更温和的话说出来。

• 能把成绩数据整理成清楚结构。
• 能用函数算平均分、强项、弱项。
• 能让 AI 根据函数结果给 3 条建议。
• 能避免把学生评价写得太打击。

7.2 核心理论

理论不是背概念，而是帮你判断项目为什么这样设计。下面这些规则会在代码里反复出现。

• 核心理论：Function Calling 的重点不是让 AI 执行代码，而是让 AI 决定“应该调用哪个工具”。真正执行函数的是你的程序。
• 可靠性理论：数学计算、成绩统计、日期规则等确定性任务，应该交给函数完成，避免让模型猜。
• 回传理论：函数执行完以后，要把结果回传给模型，模型再把结果解释成学生能懂的话。
• 输入契约：先规定用户要给什么资料。本课的输入要围绕“AI学习管家”，不要让用户随便输入到程序无法处理。
• 输出契约：先规定 AI 必须交出什么结果。本课重点是“数据分析、函数协作、学习建议”，所以输出要能被人读懂，也要方便程序检查。
• 验证思维：AI 的一次好结果不等于项目可靠。至少用正常输入、边界输入、异常输入各测一次。
• 安全边界：API Key 是密码，不能写进浏览器前端，不能发截图，不能提交到公开仓库。

7.3 课堂讲解

这一课的项目是“AI学习管家”，重点是“数据分析、函数协作、学习建议”。你可以把它当成一个小实验：先给它一个清楚输入，再观察代码里哪些地方用到了 Function Calling + JSON。课堂里我们不会一上来就追求复杂功能，而是先把最小版本做出来。最小版本跑通以后，你再改输入、改提示词、改输出格式，变化就会看得很清楚。

这几课开始让 AI 和函数合作。模型听懂人的话，函数做确定的事。这样的分工很像课堂小组：一个同学负责读题，一个同学负责计算。

本课有一条很实用的学习线索：先问“用户到底给了什么”，再问“程序希望拿到什么”。比如你可以试这些输入：数学72，英语88，科学64；语文90，数学91，英语89；数学45，英语80，科学78。这些输入故意有简单的，也有容易出问题的。正常输入能帮你确认功能；短输入、空输入、奇怪输入能帮你发现系统边界。

写代码时建议你分三轮。第一轮只跑通官方调用，不加自己的想法；第二轮把输入换成自己的例子，看看结果是否还合理；第三轮才开始改结构，比如增加字段、加错误提示、做网页交互。这个顺序有点慢，但很稳。真正浪费时间的不是慢，而是一下子改太多，最后不知道错在哪里。

不要让模型负责精确计算。它可以解释过程，但平均分、面积、乘法结果应该由函数给出。

理论部分要和代码一起看。比如“输入契约”不是一个漂亮词，它在代码里就是长度检查、必填字段、表单校验；“输出契约”也不是空话，它在代码里就是 JSON Schema、固定字段或页面渲染规则。你每写一行检查代码，都是在告诉系统：什么结果可以接受，什么结果需要退回去重新处理。

课堂里可以把同桌当成第一个用户。你把项目跑给同桌看，让对方换一个输入，观察系统会不会乱。很多问题都是别人随手一试才出现的，比如输入太短、问题太模糊、连续点击按钮、图片看不清。能处理这些小麻烦，作品就会从“我电脑上能跑”变成“别人也能用”。

最后做复盘时，不要只写“我学会了调用 API”。可以写得更具体：我学会了怎样限制输入，怎样让输出固定，怎样判断结果不可靠，怎样把报错变成用户看得懂的提示。这样的复盘有用，因为下一课你真的会再次用到它。

课堂讨论题

• 如果把“AI学习管家”交给低年级学生使用，哪一步最容易让他们困惑？
• 这个项目里，哪些事情适合交给模型，哪些事情应该交给普通代码？
• 如果模型给出一个看起来不错但没有依据的答案，你打算怎样提醒用户？
• 你能不能把今天的项目换一个主题，但保持同样的输入、处理、输出结构？
• 如果只能保留一个测试用例，你会保留正常输入、边界输入还是异常输入？为什么？

7.4 先看例子

先把例子看懂，再动手写代码。你不需要一次记住所有概念，先能说清楚“输入是什么、输出是什么、程序要检查什么”。

{
  "average": 74.7,
  "best_subject": "英语",
  "weak_subject": "科学"
}

你可以替换成这些输入

• 数学72，英语88，科学64。
• 语文90，数学91，英语89。
• 数学45，英语80，科学78。
• 只输入数学70。
• 数学目标85，现在72。

7.5 完整代码实现

下面同时给出 Node.js 和 Python 两套完整最小实现。先任选一种原样跑通，再改输入、改提示词、改输出格式。

Node.js 运行方式

1. 新建文件 lesson-07.mjs，把下面完整代码放进去。
2. 在终端运行：npm init -y
3. 安装依赖：npm install openai
4. 设置环境变量 OPENAI_API_KEY。Windows PowerShell 示例：$env:OPENAI_API_KEY="你的密钥"
5. 运行：node lesson-07.mjs
6. 把最后一行的示例输入换成你自己的测试内容。

Node.js 完整代码

import OpenAI from "openai";

const client = new OpenAI();
const MODEL = process.env.OPENAI_MODEL || "gpt-5.5";

const tools = [
  {
    type: "function",
    name: "analyze_scores",
    description: "分析学生各科成绩，返回平均分、强项和弱项。",
    parameters: {
      type: "object",
      properties: {
        scores: {
          type: "array",
          items: {
            type: "object",
            properties: {
              subject: { type: "string" },
              score: { type: "number" },
            },
            required: ["subject", "score"],
            additionalProperties: false,
          },
        },
      },
      required: ["scores"],
      additionalProperties: false,
    },
    strict: true,
  },
];

function analyzeScores(scores) {
  const total = scores.reduce((sum, item) => sum + item.score, 0);
  const average = Number((total / scores.length).toFixed(1));
  const sorted = [...scores].sort((a, b) => a.score - b.score);
  return {
    average,
    weak_subject: sorted[0].subject,
    best_subject: sorted[sorted.length - 1].subject,
  };
}

let input = [
  { role: "user", content: "数学72，英语88，科学64。请帮我分析，并给今天的复习建议。" },
];

let response = await client.responses.create({ model: MODEL, input, tools });
input.push(...response.output);

for (const item of response.output) {
  if (item.type !== "function_call") continue;
  if (item.name === "analyze_scores") {
    const args = JSON.parse(item.arguments);
    const result = analyzeScores(args.scores);
    input.push({
      type: "function_call_output",
      call_id: item.call_id,
      output: JSON.stringify(result),
    });
  }
}

response = await client.responses.create({
  model: MODEL,
  input,
  tools,
  instructions: "根据函数结果给建议。语气鼓励，建议要具体，每条不超过 25 字。",
});

console.log(response.output_text);

Python 运行方式

1. 新建文件 lesson-07.py，把下面完整代码放进去。
2. 建议新建虚拟环境后再安装依赖。
3. 安装依赖：pip install openai
4. 设置环境变量 OPENAI_API_KEY。Windows PowerShell 示例：$env:OPENAI_API_KEY="你的密钥"
5. 运行：python lesson-07.py
6. 把 main 里的示例输入换成你自己的测试内容。

Python 完整代码

from openai import OpenAI
import json
import os

client = OpenAI()
MODEL = os.getenv("OPENAI_MODEL", "gpt-5.5")

tools = [
    {
        "type": "function",
        "name": "analyze_scores",
        "description": "分析学生各科成绩，返回平均分、强项和弱项。",
        "parameters": {
            "type": "object",
            "properties": {
                "scores": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "subject": {"type": "string"},
                            "score": {"type": "number"},
                        },
                        "required": ["subject", "score"],
                        "additionalProperties": False,
                    },
                }
            },
            "required": ["scores"],
            "additionalProperties": False,
        },
        "strict": True,
    }
]


def analyze_scores(scores):
    total = sum(item["score"] for item in scores)
    average = round(total / len(scores), 1)
    sorted_scores = sorted(scores, key=lambda item: item["score"])
    return {
        "average": average,
        "weak_subject": sorted_scores[0]["subject"],
        "best_subject": sorted_scores[-1]["subject"],
    }


input_items = [
    {"role": "user", "content": "数学72，英语88，科学64。请帮我分析，并给今天的复习建议。"}
]

response = client.responses.create(model=MODEL, input=input_items, tools=tools)
input_items += response.output

for item in response.output:
    if item.type != "function_call":
        continue
    if item.name == "analyze_scores":
        args = json.loads(item.arguments)
        result = analyze_scores(args["scores"])
        input_items.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps(result, ensure_ascii=False),
        })

response = client.responses.create(
    model=MODEL,
    input=input_items,
    tools=tools,
    instructions="根据函数结果给建议。语气鼓励，建议要具体，每条不超过 25 字。",
)

print(response.output_text)

7.6 跟着做

1. 设计成绩输入格式。
2. 写 analyze_scores 函数计算统计结果。
3. 让 AI 只根据函数结果写建议。
4. 输出鼓励、弱项、今日任务三个部分。
5. 用不同成绩测试建议是否合理。

7.7 常见错误

• 让 AI 直接猜平均分，数字可能不准。
• 建议太长，学生看完不知道先做什么。
• 只指出问题，没有给行动。
• 没有处理成绩缺失或格式错误。

7.8 课后练习

1. 加入“目标分数”输入，例如数学想达到 85。
2. 让学习管家输出 7 天小计划。
3. 每一天最多 2 个任务，避免太重。

7.9 自测清单

• 平均分是不是函数算出来的？
• 建议有没有和弱项对应？
• 输出是否适合学生阅读？
• 我有没有测试缺少一门成绩的情况？