文本契约驱动 GLM-5.1，让 AI 写出可用代码

AI 编程工具已经从“生成一段代码”逐渐进入“参与工程开发”的阶段。对于开发者来说，真正重要的问题不再是模型能不能写出函数，而是它能否理解约束、保持上下文一致、生成可维护代码，并在接口、状态、性能和异常处理上符合工程要求。

GLM-5.1 的价值，正适合放在这种工程化场景中观察。相比简单的问答式调用，更合理的使用方式是把需求转化为清晰的“文本契约”：提前定义类结构、方法签名、状态流转、输入输出、异常边界和性能指标，再让模型在明确约束下生成代码。这样做可以显著降低 AI 代码跑偏、字段不一致、逻辑断层和后期返工的问题。

本文以一个“方块世界”项目为例，系统拆解 GLM-5.1 在复杂代码生成、状态机建模、地形算法、后端接口设计和工程调试中的使用方法。

一、为什么复杂项目更适合测试 AI 编程能力

很多 AI 编程演示只停留在“写一个函数”“生成一个页面”“补全一段 SQL”这样的轻量任务。但真实工程通常不是单点问题，而是多个模块之间的协同：类之间要有继承关系，状态之间要能流转，接口返回要稳定，缓存策略要合理，性能指标也要可控。

“方块世界”项目虽然看起来像游戏 Demo，但它实际覆盖了很多典型工程问题。例如，方块需要具备状态变化能力，地形需要由噪声算法生成，后端需要根据坐标返回区块数据，前端还要处理渲染顺序和数据量限制。只要某个字段、状态或返回结构不一致，整个系统就会出现连锁问题。

在连续两周的多场景测试中，平均每天调用约 27 次，任务覆盖 Web 后端、数据处理、算法实现和硬件控制等方向。整体来看，GLM-5.1 在结构化需求下表现更稳定，尤其适合“先定义规则，再生成代码”的开发方式。

二、核心方法：文本契约驱动开发

所谓文本契约驱动开发，可以理解为把自然语言需求写成接近工程规范的任务说明。它不是简单告诉模型“帮我写个功能”，而是把功能边界拆解清楚，让模型知道哪些内容必须遵守，哪些内容不能自由发挥。

例如，如果要生成一个草方块类，普通提示词可能是：

帮我写一个草方块类。

这种写法过于模糊，模型可能随意设计字段、方法和状态逻辑，后续很难接入项目。

更好的写法是：

请用 Python 3.11 编写 DewGrassBlock 类：
1. 继承 Block 基类；
2. 内部维护 _phase 和 _dew_level；
3. _dew_level 范围为 0.0 到 1.0；
4. update(delta_time) 根据时间更新露水值；
5. 夜晚且露水值大于等于 0.9 时触发 _harvest()；
6. on_click(player) 在露水值大于 0.5 时消耗 0.3，并返回种子列表；
7. 禁止使用外部库；
8. 所有状态变化必须基于 delta_time。

这种提示词的优势在于，它提前定义了继承关系、内部字段、状态范围、触发条件和依赖限制。模型生成代码时，会围绕这些约束展开，而不是重新发明一套不兼容的结构。

文本契约越清晰，AI 生成代码越容易被测试、复用和维护。

三、API 调用：用兼容接口降低接入成本

GLM-5.1 支持 OpenAI Compatible 风格接口，因此可以通过类似 /v1/chat/completions 的方式接入。对于已经使用 OpenAI SDK、自动化脚本或 IDE 插件的团队来说，这种兼容方式可以减少迁移成本。

下面是一个简化后的 Bash 调用示例：

glm51() {
  local prompt="$1"
  local model="${2:-glm-5.1-flash}"
  local api_key="YOUR_API_KEY"
  local base_url="https://open.bigmodel.cn/api/paas/v4"

  curl -X POST "$base_url/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $api_key" \
    -d '{
      "model": "'"$model"'",
      "messages": [
        {
          "role": "user",
          "content": "'"$prompt"'"
        }
      ],
      "stream": false
    }' | jq -r '.choices[0].message.content'
}

如果团队同时测试 GLM、Claude、GPT 等多个模型，也可以通过 koalaapi 这类大模型 API 聚合平台作为统一接入层，减少多套接口重复配置带来的维护成本。

四、地形生成：让模型遵守算法边界

在方块世界中，地形生成是一个很适合测试模型工程能力的任务。它既需要算法逻辑，又需要性能意识。如果提示词只写“生成一个随机地图”，模型可能输出不可控的随机数逻辑，难以复现，也不适合工程使用。

更合理的提示词可以这样写：

请用 Python 3.11 编写 FractalNoise 类：
1. 构造函数包含 scale=100.0、octaves=4、persistence=0.5、lacunarity=2.0；
2. 禁止使用 numpy；
3. 只能基于 math.sin 和 math.cos 实现；
4. 提供 noise2d(x, y) 方法；
5. 输出结果归一化到 -1.0 到 1.0；
6. 代码需要包含类型注解和必要注释。

这种写法把模型限制在明确的数学契约里。它不需要依赖大型第三方库，也不会生成难以部署的复杂逻辑。实际测试中，在 Raspberry Pi 4 上生成 1024×1024 高度图约 1.2 秒，说明这种轻量实现具备一定实用价值。

AI 编程并不是让模型随意生成“看起来能跑”的代码，而是让它在约束条件下生成“可以进入工程流程”的代码。

五、状态机：复杂逻辑要先定义规则

方块世界中的泥土、湿泥土、草种、草芽和草方块之间存在状态变化。这样的逻辑如果直接写成大量 if else，后期很容易失控。更好的方式是提前定义状态枚举和转换规则，再让模型生成状态机。

状态集合可以先写清楚：

DIRT
WET_DIRT
GRASS_SEED
GRASS_SPROUT
GRASS_BLOCK

状态转换规则如下：

DIRT + rain -> WET_DIRT
WET_DIRT + sun -> GRASS_SEED
GRASS_SEED + time_pass -> GRASS_SPROUT
GRASS_SPROUT + time_pass -> GRASS_BLOCK

基于这些规则，可以要求模型生成 BlockStateMachine：

from enum import Enum
from typing import Dict, Tuple, List


class BlockState(Enum):
    DIRT = "dirt"
    WET_DIRT = "wet_dirt"
    GRASS_SEED = "grass_seed"
    GRASS_SPROUT = "grass_sprout"
    GRASS_BLOCK = "grass_block"


class BlockEvent(Enum):
    RAIN = "rain"
    SUN = "sun"
    TIME_PASS = "time_pass"


class BlockStateMachine:
    def __init__(self) -> None:
        self.state = BlockState.DIRT
        self.history: List[BlockState] = [self.state]
        self.transitions: Dict[Tuple[BlockState, BlockEvent], BlockState] = {
            (BlockState.DIRT, BlockEvent.RAIN): BlockState.WET_DIRT,
            (BlockState.WET_DIRT, BlockEvent.SUN): BlockState.GRASS_SEED,
            (BlockState.GRASS_SEED, BlockEvent.TIME_PASS): BlockState.GRASS_SPROUT,
            (BlockState.GRASS_SPROUT, BlockEvent.TIME_PASS): BlockState.GRASS_BLOCK,
        }

    def apply(self, event: BlockEvent) -> BlockState:
        next_state = self.transitions.get((self.state, event), self.state)
        self.state = next_state
        self.history.append(next_state)
        return self.state

这类代码的优势是规则集中、可测试、可扩展。如果后续要加入“干旱”“踩踏”“施肥”等事件，只需要扩展状态转换表，而不是重写整段业务逻辑。

六、后端接口：提前定义返回边界和缓存策略

在工程项目中，AI 生成接口代码时最容易出现两个问题：一是返回字段不稳定，二是数据量不可控。因此，在让模型生成后端接口前，需要提前写清楚接口路径、参数、返回结构、缓存策略和性能边界。

例如，区块接口可以这样定义：

请用 Flask 编写 /api/world/chunk 接口：
1. 接收 x、y、z 三个查询参数；
2. 返回指定区块范围内的方块列表；
3. blocks 数组最多返回 2048 个方块；
4. 使用 lru_cache 缓存 get_chunk_data(x, y, z)；
5. 最大缓存区块数为 128；
6. 数据库操作用内存字典模拟；
7. 禁止额外 IO；
8. 返回结果按 z 轴排序。

示例代码如下：

from functools import lru_cache
from flask import Flask, request, jsonify

app = Flask(__name__)

WORLD_DATA = {}


@lru_cache(maxsize=128)
def get_chunk_data(x: int, y: int, z: int):
    blocks = []

    for i in range(16):
        for j in range(16):
            for k in range(8):
                if len(blocks) >= 2048:
                    break
                blocks.append({
                    "x": x * 16 + i,
                    "y": y * 16 + j,
                    "z": z * 8 + k,
                    "type": "grass_block"
                })

    return sorted(blocks, key=lambda item: item["z"])


@app.route("/api/world/chunk")
def chunk():
    x = int(request.args.get("x", 0))
    y = int(request.args.get("y", 0))
    z = int(request.args.get("z", 0))

    return jsonify({
        "chunk": {"x": x, "y": y, "z": z},
        "blocks": get_chunk_data(x, y, z)
    })

部署到 2 核 4G 云服务器后，可以使用 ApacheBench 做一个简单压测：

ab -n 1000 -c 100 "http://server/api/world/chunk?x=0&y=0&z=0"

在测试环境中，平均响应时间稳定在 87ms 左右，QPS 达到 115。这个结果说明，只要提前把缓存、返回数量和排序规则写进任务描述，AI 生成的后端代码也可以更接近真实工程要求。

七、常见问题与处理方法

使用 GLM-5.1 做工程任务时，有几个问题需要提前注意。

第一是 API Key 管理。不要把 Key 直接写进项目代码，可以单独放入本地文件，并限制权限：

echo "YOUR_API_KEY" > ~/.glm_api_key
chmod 600 ~/.glm_api_key

脚本中读取：

api_key=$(cat ~/.glm_api_key)

这样可以降低误提交和泄露风险。

第二是流式响应完整性。长代码生成时，如果使用 stream: true 出现提前停止，可以切换到 stream: false 复测。如果非流式输出完整，问题大概率出在流式输出链路；如果两种方式都不完整，就需要检查提示词是否过长、网络是否稳定，或者输出限制是否过低。

第三是长代码生成要加完整性锚点。比如在提示词末尾加入：

请输出完整代码，不要省略 import、类定义、辅助函数和入口函数。
如代码较长，请继续输出后续部分，不要用“此处省略”代替。

在长代码任务中，加入这类约束后，完整率可以从约 65% 提升到 92%。这说明很多时候模型不是不会写，而是没有被明确要求“完整输出”。

八、不要只看榜单，更要建立自己的评估集

模型评测榜单有参考价值，但不能完全代表实际项目效果。不同团队的技术栈、代码风格、业务复杂度和容错要求都不一样。更可靠的做法是建立自己的 Prompt 评估集。

例如，可以准备 10 个真实工程任务：

1. 生成状态机
2. 编写分页接口
3. 优化 SQL 查询
4. 生成单元测试
5. 重构复杂函数
6. 编写缓存逻辑
7. 生成数据清洗脚本
8. 设计错误处理机制
9. 输出接口文档
10. 分析性能瓶颈

然后用统一标准评估模型输出，比如：

1. 类型是否一致
2. 接口是否稳定
3. 是否能运行
4. 是否包含异常处理
5. 是否符合项目风格
6. 是否容易维护

在一组真实场景测试中，GLM-5.1 类型一致性得分达到 91%，Opus 得分为 88%。这类结果虽然不一定适用于所有项目，但对具体团队的模型选型更有参考价值。

九、总结：AI 编程的关键是约束清晰

GLM-5.1 的工程化使用经验说明，AI 编程效率的提升并不只来自模型能力本身，更来自开发者如何描述任务、拆分需求和定义边界。

如果提示词只是“帮我写一个功能”，模型很容易生成一段看似完整但难以接入项目的代码。相反，如果任务中包含类结构、方法签名、状态规则、性能指标、异常处理和输出格式，模型就更容易生成可测试、可维护、可继续迭代的结果。

对于开发团队来说，真正值得沉淀的不是某一次模型输出，而是一套可复用的文本契约模板。把需求写清楚，把边界定义清楚，把测试标准提前写清楚，AI 才能从“代码生成器”变成更可靠的工程协作工具。