掘金本周最热

【SpringBoot 3.x 第254节】夯爆了，数据库访问性能优化实战详解！

bug菌 — Wed, 27 May 2026 09:58:16 GMT

🏆 本文收录于《滚雪球学 Spring Boot 3.x》专栏，专注 Spring Boot 3.x 系统学习与实战进阶，内容持续更新中。

本专栏致力于打造高质量、体系化的 Spring Boot 3.x 学习路线，从零基础入门到进阶实战，帮助你快速掌握核心知识与企业级开发经验。 📌 想快速定位学习内容，可查看：【Spring Boot 3 教程导航帖】

🎉 当前专栏限时优惠中：一次订阅，终身阅读，后续更新章节全部免费解锁 👉 立即订阅 👈️ 🎁 想系统打通 Spring Boot 各主流版本？还可以查看： 👉 《Spring Boot 2.x 实战》 👉 《Spring Boot 3.x 实战》 👉 《Spring Boot 4.x 实战》

🚀 推荐合集：《Spring Boot 全栈实战合集》，一站式覆盖 Spring Boot 2.x、3.x、4.x 核心特性、项目实战与架构进阶内容。

演示环境说明：

开发工具：IDEA 2021.3

JDK版本： JDK 17（推荐使用 JDK 17 或更高版本，因为 Spring Boot 3.x 系列要求 Java 17，Spring Boot 3.5.4 基于 Spring Framework 6.x 和 Jakarta EE 9，它们都要求至少 JDK 17。）

Spring Boot版本：3.5.4（于25年7月24日发布）

Maven版本：3.8.2 （或更高）

Gradle：（如果使用 Gradle 构建工具的话）：推荐使用 Gradle 7.5 或更高版本，确保与 JDK 17 兼容。

操作系统：Windows 11

1. 为什么数据库访问性能会成为系统瓶颈？

在大多数业务系统中，数据库访问几乎一定会出现在性能链路的中心位置。很多初学者在写 Spring Boot 应用时，往往把注意力集中在 Controller 是否能正常返回、Service 是否能完成业务逻辑，却忽视了最容易被放大的问题：数据库访问次数过多、单次 SQL 过慢、索引不合理、连接池配置不当、ORM 自动生成了低效 SQL。

数据库性能问题有一个典型特征：它不一定在功能上线当天就暴露出来，而是在数据量增长、并发升高、业务链路变长之后，逐步演化为“偶发卡顿”“接口超时”“线程堆积”“数据库 CPU 飙高”等症状。此时，系统表面看起来像是“Java 代码慢”，实际上往往是数据库访问策略出了问题。

在 Spring Boot 3.x 中，数据库访问方式非常灵活。你可以使用 JDBC、JdbcTemplate、Spring Data JPA、MyBatis，甚至是 R2DBC。不同方案有不同的抽象层级，但本质都绕不开同一个问题：如何让数据访问更高效、更稳定、更可观测。

如果把数据库访问优化比作一条链路，那么链路上至少有四个关键节点：

数据结构设计：索引、字段类型、范式与反范式
SQL 设计：查询条件、排序、分页、聚合、更新方式
连接与并发：连接池、事务、锁、线程调度
应用层组织：ORM 生成 SQL、缓存、批处理、异步化

任何一个节点失衡，都可能拖垮整体性能。

2. Spring Boot 3.x 视角下的数据库访问栈

Spring Boot 3.x 带来的变化，不只是版本号升级，更重要的是基础生态的现代化：JDK 17 起步、Jakarta 命名空间迁移、对现代 observability 的更好支持，以及与 Hibernate 6、Spring Data 3 的适配。

从数据库访问的角度看，一个典型的 Spring Boot 3.x 应用通常会经过如下链路：

示意图绘制如下，仅供参考：

这里面最容易出问题的地方有三个：

Repository 层隐藏了 SQL 复杂度，开发者容易忽略真实执行语句。
连接池把“连接创建成本”隐藏起来，开发者容易误以为连接是免费的。
ORM 将对象世界映射到关系世界时，可能产生额外查询、N+1、隐式 join、分页偏差等问题。

在 Spring Boot 3.x 中，推荐你建立一种思维：不要只看“代码写得简洁不简洁”，更要看“最终执行的 SQL 是否合理”。

3. 性能优化的总原则：先定位，再改造，再验证

数据库访问优化不是“经验主义艺术”，而是一个可重复的工程过程。最佳实践通常遵循下面这条主线：

示意图绘制如下，仅供参考：

这条链路强调两个关键事实：

你不能凭感觉改 SQL，必须看执行计划、扫描行数、实际耗时。
你不能只优化数据库，还要回到 Java 代码，确认是不是 ORM 或调用方式导致的低效访问。

很多优化失败，都是因为直接跳到了“加索引”这一步。事实上，索引只是优化手段之一，不是万能钥匙。

4. 索引优化：从“能查到”到“查得快”

4.1 索引是什么

索引本质上是一种加速查找的数据结构。对于关系型数据库来说，常见的是 B+ 树索引。你可以把索引理解为一本书的目录：没有目录，想找某一页内容只能从头翻；有目录，就能快速定位。

但索引不是免费午餐。索引会占用存储空间，也会降低写入性能，因为每次插入、更新、删除，数据库都要维护索引结构。

因此，索引优化的第一原则不是“多建几个”，而是“建对、用对、少而精”。

4.2 适合建立索引的字段

通常来说，以下字段很适合建索引：

经常出现在 WHERE 条件中的字段
经常出现在 JOIN 条件中的字段
经常出现在 ORDER BY 中的字段
经常出现在 GROUP BY 中且基数较高的字段
业务上需要唯一性的字段，例如手机号、订单号、用户名

4.3 不适合滥用索引的场景

以下场景通常不建议盲目加索引：

字段区分度太低，例如性别、状态位
查询数据量本身很小
写入非常频繁而查询较少
条件上大量使用函数、模糊前缀、隐式类型转换

例如下面这条 SQL 看起来没问题，但其实可能无法有效使用索引：

SELECT *
FROM user_account
WHERE DATE(create_time) = '2026-04-15';

原因是对字段做了函数运算，数据库很可能无法直接利用 create_time 上的索引。

更好的写法是：

SELECT *
FROM user_account
WHERE create_time >= '2026-04-15 00:00:00'
  AND create_time <  '2026-04-16 00:00:00';

4.4 联合索引的使用顺序

联合索引不是多个单列索引的简单叠加。它遵循最左前缀原则。比如有这样一个索引：

CREATE INDEX idx_order_user_status_time ON t_order(user_id, status, create_time);

那么下面这些查询通常更容易利用索引：

SELECT * FROM t_order WHERE user_id = ?;
SELECT * FROM t_order WHERE user_id = ? AND status = ?;
SELECT * FROM t_order WHERE user_id = ? AND status = ? AND create_time >= ?;

但如果你只写：

SELECT * FROM t_order WHERE status = ?;

就可能无法充分利用这个联合索引。

4.5 覆盖索引与回表

如果查询所需字段都包含在索引里，数据库可能只扫描索引，不必再回表读取整行数据，这就是覆盖索引。覆盖索引在高并发读场景下非常重要。

例如：

SELECT user_id, status, create_time
FROM t_order
WHERE user_id = ?
  AND status = ?;

如果联合索引恰好包含这些列，那么数据库可能直接通过索引返回结果，减少一次回表访问。

4.6 索引优化的 Java 侧案例

下面这个 Repository 代码看似简单，但背后决定了是否能吃到索引红利。

package com.example.demo.repository;

import com.example.demo.entity.OrderEntity;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;

import java.time.LocalDateTime;
import java.util.List;

public interface OrderRepository extends JpaRepository<OrderEntity, Long> {

    // 通过用户ID、状态和时间范围查询订单
    // 该查询更容易命中 (user_id, status, create_time) 联合索引
    @Query("select o from OrderEntity o where o.userId = :userId and o.status = :status and o.createTime between :startTime and :endTime")
    List<OrderEntity> findByUserIdAndStatusAndCreateTimeBetween(
            @Param("userId") Long userId,
            @Param("status") Integer status,
            @Param("startTime") LocalDateTime startTime,
            @Param("endTime") LocalDateTime endTime);
}

这段代码表面上是 JPA 查询，实际上是否高效，取决于底层表结构和索引设计。你必须在表层做配合，而不是指望 ORM 自动解决一切。

4.7 索引设计的实战建议

你可以按以下顺序思考：

先看查询模式，再看表结构。
按高频过滤条件设计联合索引。
把区分度高的字段尽量放在索引前部。
避免在索引列上进行函数、计算、隐式转换。
关注是否能形成覆盖索引。
用 EXPLAIN 验证，不要凭感觉。

5. 批量操作：从单条写入到吞吐提升

5.1 单条写入为什么慢

很多新手会写出这样的代码：

for (OrderEntity order : orders) {
    orderRepository.save(order);
}

这段代码的问题在于：每次 save 都可能触发一次数据库交互。如果数据量稍大，就会出现明显的性能瓶颈。

单条写入的成本主要包括：

Java 方法调用成本
ORM 状态管理成本
SQL 发送成本
网络往返成本
数据库解析与执行成本
事务提交成本

当这些成本乘以成百上千条数据时，整体耗时会非常可观。

5.2 批量写入的核心价值

批量写入的价值不只是“少发几条 SQL”，更重要的是减少网络往返、减少事务提交次数、降低数据库解析压力。

批量操作通常有两类：

批量插入
批量更新

5.3 JPA 批量插入示例

JPA 并不是天然高性能批量工具。若使用不当，saveAll 也未必真的批量。

下面给出一个适合批量插入的 Service 示例：

package com.example.demo.service;

import com.example.demo.entity.OrderEntity;
import com.example.demo.repository.OrderRepository;
import jakarta.persistence.EntityManager;
import jakarta.persistence.PersistenceContext;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.util.List;

@Service
public class OrderBatchService {

    private final OrderRepository orderRepository;

    @PersistenceContext
    private EntityManager entityManager;

    public OrderBatchService(OrderRepository orderRepository) {
        this.orderRepository = orderRepository;
    }

    @Transactional
    public void batchInsert(List<OrderEntity> orders) {
        // 分批处理，避免一次性持有过多持久化上下文对象
        int batchSize = 50;
        for (int i = 0; i < orders.size(); i++) {
            orderRepository.save(orders.get(i));

            // 每批提交前刷新并清空，释放一部分内存压力
            if (i > 0 && i % batchSize == 0) {
                entityManager.flush();
                entityManager.clear();
            }
        }

        // 处理剩余数据
        entityManager.flush();
        entityManager.clear();
    }
}

5.4 为什么要 flush 和 clear

JPA 在持久化时会把实体放入一级缓存，也就是持久化上下文。如果你一次性插入大量数据，不及时 flush 和 clear，就会导致内存占用不断上升，同时脏检查成本也会增加。

因此，批量处理常见的写法是：

每 50 条 flush 一次
每 50 条 clear 一次

这个数字不是绝对值，需要结合业务和数据库压力测试调整。

5.5 原生 JDBC 批处理示例

在强吞吐场景下，JDBC 批处理往往比 JPA 更直接、更可控。

package com.example.demo.service;

import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.util.List;

@Service
public class OrderJdbcBatchService {

    private final JdbcTemplate jdbcTemplate;

    public OrderJdbcBatchService(JdbcTemplate jdbcTemplate) {
        this.jdbcTemplate = jdbcTemplate;
    }

    @Transactional
    public void batchInsert(List<OrderInput> inputs) {
        String sql = "INSERT INTO t_order(user_id, order_no, status, create_time) VALUES (?, ?, ?, ?)";

        // 使用 JDBC 的 batchUpdate 进行批量插入
        jdbcTemplate.batchUpdate(sql, inputs, 100, (ps, item) -> {
            ps.setLong(1, item.getUserId());
            ps.setString(2, item.getOrderNo());
            ps.setInt(3, item.getStatus());
            ps.setTimestamp(4, java.sql.Timestamp.valueOf(item.getCreateTime()));
        });
    }
}

这类写法的优点是明确、可控，缺点是业务代码和 SQL 耦合更高。

5.6 批量更新的注意点

批量更新比批量插入更容易出问题，因为更新通常伴随着条件、锁、版本号控制和业务状态流转。

建议注意以下几点：

避免逐条 update
尽量合并同类条件
注意事务范围不要过大
在高并发下考虑乐观锁
必要时拆批，防止长事务

6. 连接池：HikariCP 的核心参数与调优思路

6.1 为什么需要连接池

数据库连接不是轻量对象。每次创建连接都要经过认证、握手、初始化等流程，开销很高。连接池的作用就是复用连接，减少频繁创建和销毁的成本。

Spring Boot 3.x 默认使用 HikariCP，这是一款性能和稳定性都很出色的连接池。

6.2 连接池优化的基本思维

连接池调优不是“把最大连接数调到很大”这么简单。连接池参数要和数据库最大连接数、CPU 核数、应用并发、SQL 耗时共同决定。

连接池太小：

请求拿不到连接
应用线程阻塞
接口响应时间变长

连接池太大：

数据库压力增大
争抢严重
上下文切换增多
可能出现“连接很多但吞吐没上去”

6.3 Spring Boot 3.x 中的 Hikari 配置

下面是一个典型配置示例：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/demo?useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=utf8&rewriteBatchedStatements=true
    username: root
    password: root
    driver-class-name: com.mysql.cj.jdbc.Driver
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 30000
      idle-timeout: 600000
      max-lifetime: 1800000
      leak-detection-threshold: 2000

6.4 参数解读

maximum-pool-size：最大连接数，决定峰值时最多多少连接并发访问数据库。
minimum-idle：最小空闲连接数，保证预热和快速响应。
connection-timeout：拿连接的超时时间，太短会导致正常高峰也失败，太长会掩盖问题。
idle-timeout：空闲连接回收时间。
max-lifetime：连接最大生命周期，避免连接长期存在导致数据库侧断开。
leak-detection-threshold：连接泄漏检测阈值，排查忘记关闭连接非常有帮助。

6.5 如何判断连接池是否合理

你不能只看“连接池跑起来了”，还要看是否出现以下信号：

等待连接时间偏高
活跃连接长期接近上限
数据库 CPU 高但 TPS 没上去
业务线程被卡在获取连接阶段

在生产环境里，连接池问题常常不是根因，而是结果。真正根因往往是 SQL 太慢、事务太长、索引不合理。

7. SQL 优化联动：索引、执行计划、分页、排序、回表

7.1 SQL 优化的基本原则

SQL 优化不是“改几个关键字”就能解决，它通常与索引策略深度绑定。最有效的原则有以下几个：

让条件尽量可索引化
减少全表扫描
减少返回列数
避免无意义排序
控制分页偏移
减少回表次数

7.2 SELECT * 的问题

SELECT * 在开发阶段很方便，但在生产系统中经常带来副作用：

传输冗余字段，浪费网络带宽
取回不必要的大字段，例如 JSON、TEXT、BLOB
破坏覆盖索引的可能性
增加对象映射成本

建议只查询需要的字段。

7.3 大分页问题

下面这个分页查询在数据量很大时会越来越慢：

SELECT id, user_id, order_no, status, create_time
FROM t_order
ORDER BY create_time DESC
LIMIT 100000, 20;

原因是数据库需要先跳过前 100000 条，再返回 20 条。偏移越大，成本越高。

更好的方案是基于游标或时间、ID 做“游标翻页”：

SELECT id, user_id, order_no, status, create_time
FROM t_order
WHERE create_time < ?
ORDER BY create_time DESC
LIMIT 20;

7.4 排序问题

排序会消耗 CPU 和内存。如果排序字段上没有索引，数据库可能需要额外的 filesort。高频排序字段，特别是和过滤条件一起使用的字段，应该认真设计索引。

7.5 回表问题

当查询列不在索引中时，数据库需要先通过索引找到主键，再回到主表读取完整数据，这就是回表。回表并不总是坏事，但在高频场景下，如果回表次数太多，性能会明显下降。

7.6 使用 EXPLAIN 观察执行计划

以下信息通常很有价值：

type：访问类型，是否走索引
key：实际使用的索引
rows：预估扫描行数
Extra：是否 Using filesort、Using temporary、Using index

你不需要死记硬背所有字段，但至少要会判断：

有没有走到你想要的索引
扫描行数是不是过大
有没有排序临时表
有没有覆盖索引

8. ORM 生成 SQL 的风险点：JPA 为什么会“写出慢 SQL”

8.1 ORM 的价值与代价

ORM 的价值非常明显：

提高开发效率
降低样板代码
便于领域建模
统一事务和对象管理

但代价同样真实：

SQL 透明度下降
性能问题更隐蔽
复杂查询表达困难
容易产生 N+1 问题

Spring Data JPA 尤其适合简单 CRUD 和中等复杂度查询，但并不意味着它天然适合所有场景。

8.2 N+1 问题

N+1 是 ORM 世界最经典的性能陷阱之一。它的本质是：查询主对象一次，然后为了拿关联对象，逐条发起额外查询。

比如查询 100 个订单，再逐个查订单详情，就会变成 101 次查询。

示意图绘制如下，仅供参考：

这个问题很典型，表面上是代码写得“面向对象”，实际上却在数据库层制造了很多小查询。

8.3 懒加载与关联查询

JPA 的懒加载机制可以减少一些不必要的关联查询，但如果使用场景不当，反而会在循环中触发隐式查询。最好的做法是：

明确查询边界
需要什么就一次性查出来
在高频接口里避免不受控的关联展开

8.4 JPA 生成 SQL 的风险点

常见风险包括：

复杂方法名派生查询可读性下降
难以精确控制 join 方式
分页和排序组合后 SQL 变重
批量更新、批量删除能力有限
对数据库特性利用不足

8.5 一个看似优雅、实则危险的查询

List<OrderEntity> findByUserNameContainingAndStatusOrderByCreateTimeDesc(String userName, Integer status);

这个方法名本身没有错，但它背后的 SQL 可能会出现：

模糊查询导致索引失效
排序字段未命中索引
返回列过多
在高并发下产生大量扫描

所以，ORM 的“优雅”必须服从性能与可维护性。

9. 慢查询如何回溯到代码层：从数据库日志到 Java 方法

9.1 慢查询分析的核心目标

慢查询分析不是单纯看数据库里哪条 SQL 慢，而是要回答一个更关键的问题：这条 SQL 是从哪一段代码发出来的，为什么会这样发？

只有回到代码层，你才能真正修复问题，而不是在数据库侧做一次临时补丁。

9.2 从数据库日志出发

首先你可以借助数据库慢查询日志、执行计划、监控平台，找到耗时较高的 SQL。

慢查询日志里通常会包含：

SQL 执行时间
扫描行数
具体 SQL 文本
执行时间窗口

拿到 SQL 后，下一步是建立“SQL 到代码”的映射。

9.3 在 Spring Boot 中记录 SQL

对于开发和测试环境，开启 SQL 日志非常有帮助。

spring:
  jpa:
    show-sql: true
    properties:
      hibernate:
        format_sql: true
        highlight_sql: true
logging:
  level:
    org.hibernate.SQL: debug
    org.hibernate.orm.jdbc.bind: trace

不过要注意，生产环境不建议无脑开启过详细日志，因为会带来额外性能开销和日志噪音。

9.4 通过请求链路标识定位

更推荐的方式是给请求打上 traceId 或 requestId，把接口请求、业务日志、SQL 日志串起来。

例如，Controller 接到请求后记录一次关键日志：

package com.example.demo.web;

import jakarta.servlet.http.HttpServletRequest;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/orders")
public class OrderController {

    private static final Logger log = LoggerFactory.getLogger(OrderController.class);

    @GetMapping("/slow")
    public String slowQuery(HttpServletRequest request) {
        // 记录请求来源，便于排查慢请求对应的入口
        log.info("收到请求：uri={}, remoteAddr={}", request.getRequestURI(), request.getRemoteAddr());
        return "ok";
    }
}

如果你把日志格式统一成包含 traceId，就能在日志平台里按请求串联出整条链路。

9.5 使用 AOP 记录 Repository 或 Service 耗时

你可以在 Service 层加一个简单的耗时统计，快速定位是业务慢还是数据库慢。

package com.example.demo.aspect;

import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

@Aspect
@Component
public class CostTimeAspect {

    private static final Logger log = LoggerFactory.getLogger(CostTimeAspect.class);

    @Around("execution(* com.example.demo.service..*(..))")
    public Object recordCostTime(ProceedingJoinPoint joinPoint) throws Throwable {
        long start = System.currentTimeMillis();
        try {
            return joinPoint.proceed();
        } finally {
            long cost = System.currentTimeMillis() - start;
            // 输出方法耗时，帮助判断是否为慢调用入口
            log.info("方法耗时：{}#{}，{}ms",
                    joinPoint.getSignature().getDeclaringTypeName(),
                    joinPoint.getSignature().getName(),
                    cost);
        }
    }
}

9.6 把慢 SQL 反查回 Repository 方法

如果你使用 JPA，可以通过以下方式反查：

看 SQL 文本是否与某个 @Query 对应
看 Repository 方法名是否生成了该 SQL
搜索项目中涉及该表名的所有 Repository
在业务日志里加入方法级别埋点
使用性能分析工具定位调用栈

9.7 一个实用建议：为复杂查询手写明确的方法名

与其让 ORM 自动拼 SQL，不如为高频关键查询写明确的方法接口，例如：

@Query("select new com.example.demo.dto.OrderSummaryDTO(o.id, o.orderNo, o.status, o.createTime) " +
       "from OrderEntity o where o.userId = :userId and o.status = :status order by o.createTime desc")
List<OrderSummaryDTO> findOrderSummary(Long userId, Integer status);

这样做的好处是：

业务含义清晰
SQL 边界明确
DTO 返回更轻量
便于优化索引和执行计划

10. Spring Data JPA 与原生 SQL 的选择边界

10.1 不要把选择变成信仰之争

很多团队会陷入“JPA 好还是 MyBatis 好”的争论。实际上，真正应该讨论的是：这个场景下哪种方式更适合当前性能目标、团队能力和维护成本。

Spring Data JPA 的优势：

开发效率高
对简单 CRUD 非常友好
领域对象表达自然
事务与实体状态管理方便

原生 SQL 的优势：

对执行计划和语法控制更强
复杂查询更容易精确表达
更容易做性能极限优化
适合报表、统计、复杂联表和批量任务

10.2 适合用 JPA 的场景

单表 CRUD
简单条件查询
中等复杂度分页列表
以业务建模为中心的领域服务
不追求极限性能的普通后台系统

10.3 适合用原生 SQL 的场景

高并发核心接口
复杂联表查询
大数据量统计和聚合
批量写入、批量更新
需要精确控制索引、Hint、排序、分页方式的场景

10.4 选择边界的判断标准

你可以用以下四个问题来判断：

这条查询是否处在核心链路上？
是否对性能、延迟非常敏感？
SQL 是否明显复杂到 ORM 表达困难？
团队是否有能力维护手写 SQL？

如果这四个问题里有两个以上答案偏向“是”，那么原生 SQL 往往更合适。

10.5 JPA 与原生 SQL 的组合策略

更现实的做法不是二选一，而是组合使用：

主流程、简单 CRUD 用 JPA
核心性能链路用原生 SQL
批量处理用 JdbcTemplate 或原生批量能力
报表统计用原生 SQL 或专门的数据访问层

这才是大多数中大型项目更健康的实践。

11. 一个完整的性能优化案例：订单查询与批处理改造

下面我们用一个贴近业务的案例，把前面讲的索引、SQL、批量、连接池、ORM 风险串起来。

11.1 场景背景

某电商后台有一个“订单查询”和“订单导入”功能：

订单查询接口经常超时
导入接口在批量导入 5 万条数据时非常慢
数据库 CPU 偶尔飙高
业务同学感觉“JPA 写起来很方便，但一上线就卡”

11.2 初始版本的问题

订单表结构大致如下：

CREATE TABLE t_order (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    user_id BIGINT NOT NULL,
    order_no VARCHAR(64) NOT NULL,
    status INT NOT NULL,
    total_amount DECIMAL(18,2) NOT NULL,
    create_time DATETIME NOT NULL,
    update_time DATETIME NOT NULL
);

初始查询代码：

package com.example.demo.service;

import com.example.demo.entity.OrderEntity;
import com.example.demo.repository.OrderRepository;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public class OrderQueryService {

    private final OrderRepository orderRepository;

    public OrderQueryService(OrderRepository orderRepository) {
        this.orderRepository = orderRepository;
    }

    public List<OrderEntity> queryByUserId(Long userId) {
        // 直接按用户ID查询订单列表
        return orderRepository.findByUserIdOrderByCreateTimeDesc(userId);
    }
}

Repository：

package com.example.demo.repository;

import com.example.demo.entity.OrderEntity;
import org.springframework.data.jpa.repository.JpaRepository;

import java.util.List;

public interface OrderRepository extends JpaRepository<OrderEntity, Long> {

    // 根据用户ID查询订单并按时间倒序排列
    List<OrderEntity> findByUserIdOrderByCreateTimeDesc(Long userId);
}

11.3 问题分析

表面上看，这段代码很简单，但问题可能有：

create_time 没有合适索引，排序慢
返回实体过多，包含不必要字段
订单列表分页不合理
查询条件缺少状态过滤，返回数据太多
JPA 加载关联对象导致额外查询

11.4 优化方案一：补充合理索引

CREATE INDEX idx_order_user_time ON t_order(user_id, create_time DESC);
CREATE INDEX idx_order_user_status_time ON t_order(user_id, status, create_time DESC);

这样，用户维度的时间倒序列表更容易命中索引。

11.5 优化方案二：使用 DTO 投影减少数据量

package com.example.demo.dto;

import java.math.BigDecimal;
import java.time.LocalDateTime;

public class OrderSummaryDTO {

    private Long id;
    private String orderNo;
    private Integer status;
    private BigDecimal totalAmount;
    private LocalDateTime createTime;

    public OrderSummaryDTO(Long id, String orderNo, Integer status, BigDecimal totalAmount, LocalDateTime createTime) {
        this.id = id;
        this.orderNo = orderNo;
        this.status = status;
        this.totalAmount = totalAmount;
        this.createTime = createTime;
    }

    public Long getId() {
        return id;
    }

    public String getOrderNo() {
        return orderNo;
    }

    public Integer getStatus() {
        return status;
    }

    public BigDecimal getTotalAmount() {
        return totalAmount;
    }

    public LocalDateTime getCreateTime() {
        return createTime;
    }
}

Repository 改造：

package com.example.demo.repository;

import com.example.demo.dto.OrderSummaryDTO;
import com.example.demo.entity.OrderEntity;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;

import java.util.List;

public interface OrderRepository extends JpaRepository<OrderEntity, Long> {

    @Query("select new com.example.demo.dto.OrderSummaryDTO(o.id, o.orderNo, o.status, o.totalAmount, o.createTime) " +
           "from OrderEntity o where o.userId = :userId order by o.createTime desc")
    List<OrderSummaryDTO> findOrderSummaryByUserId(@Param("userId") Long userId);
}

11.6 优化方案三：分页改成游标翻页

package com.example.demo.repository;

import com.example.demo.dto.OrderSummaryDTO;
import com.example.demo.entity.OrderEntity;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;

import java.time.LocalDateTime;
import java.util.List;

public interface OrderRepository extends JpaRepository<OrderEntity, Long> {

    @Query("select new com.example.demo.dto.OrderSummaryDTO(o.id, o.orderNo, o.status, o.totalAmount, o.createTime) " +
           "from OrderEntity o where o.userId = :userId and o.createTime < :beforeTime order by o.createTime desc")
    List<OrderSummaryDTO> findOrderSummaryByUserIdAndBeforeTime(
            @Param("userId") Long userId,
            @Param("beforeTime") LocalDateTime beforeTime,
            org.springframework.data.domain.Pageable pageable);
}

11.7 批量导入改造

初始导入逻辑：

for (OrderEntity order : orders) {
    orderRepository.save(order);
}

改造成批处理：

package com.example.demo.service;

import com.example.demo.entity.OrderEntity;
import jakarta.persistence.EntityManager;
import jakarta.persistence.PersistenceContext;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.util.List;

@Service
public class OrderImportService {

    @PersistenceContext
    private EntityManager entityManager;

    @Transactional
    public void importOrders(List<OrderEntity> orders) {
        // 每批处理的数量，具体值需要压测后确定
        int batchSize = 100;

        for (int i = 0; i < orders.size(); i++) {
            entityManager.persist(orders.get(i));

            if (i > 0 && i % batchSize == 0) {
                // 刷新到数据库并清理持久化上下文
                entityManager.flush();
                entityManager.clear();
            }
        }

        entityManager.flush();
        entityManager.clear();
    }
}

11.8 优化前后的效果预期

经过这些改造后，通常可以看到：

查询耗时下降
数据库扫描行数减少
导入吞吐提升
连接池等待时间下降
CPU 峰值降低

关键不在于“代码看起来更短”，而在于“数据访问路径更合理”。

12. 常见误区与排查清单

12.1 误区一：加索引一定更快

不是。索引会提升读性能，但也会增加写成本。是否加索引，取决于查询与写入的平衡。

12.2 误区二：JPA 一定比手写 SQL 好维护

对简单 CRUD 来说，JPA 的确方便；但对复杂查询、高并发链路，手写 SQL 往往更清晰、更高效。

12.3 误区三：连接池越大越好

不是。连接池应该和数据库能力、SQL 耗时、并发模型一起设计。

12.4 误区四：慢查询只需要改数据库

不是。很多慢查询根源是代码层的查询方式不合理，例如循环查询、N+1、DTO 设计不合理、分页方式不当。

12.5 排查清单

你可以按这个顺序排查：

是否有慢 SQL 日志
SQL 是否命中预期索引
扫描行数是否过大
是否存在 N+1
是否存在 SELECT *
是否存在大偏移分页
是否存在长事务
连接池是否耗尽
ORM 是否生成了意外 SQL
是否能用 DTO、原生 SQL 或批量操作改善

13. 总结：把性能优化做成工程能力

数据库访问优化，不是某一个工具的专属能力，而是贯穿模型设计、SQL 编写、ORM 使用、事务控制、连接池配置、监控排查的系统工程。

在 Spring Boot 3.x 时代，开发者更应该建立下面这套方法论：

用 JPA 提升开发效率，但不要被 ORM 绑架
用索引提升查询效率，但不要迷信索引
用批量处理提升写入吞吐，但要注意事务和内存
用连接池复用昂贵资源，但要和数据库能力匹配
用日志、监控、执行计划把慢查询精准定位到代码层
对核心链路，敢于选择原生 SQL 与 DTO 投影

真正高质量的数据库访问优化，不是“把 SQL 调快一点”这么简单，而是把数据访问从“能跑”提升到“稳定、可观测、可扩展”。

如果你能把本文的思路真正落到项目里，你会发现性能优化并不是玄学，而是一种可以不断复用、持续沉淀的工程能力。

...

ok，同学们，本节课就上到这儿，下课~

🧧 学习福利 · 限时开放 🧧

当然，无论你是计算机专业在读学生，还是对编程充满兴趣的入门者，都强烈建议系统学习SpringBoot全体系专栏：👉 「滚雪球学 Spring Boot」；涵盖SpringBoot所有教学内容。

该专栏以“循序渐进 + 实战驱动”为核心理念，从基础到进阶到就业到架构师逐层展开，帮助你快速建立完整的 Spring Boot 技术体系，带你玩转SpringBoot框架。

📌 学习承诺： 通过该专栏，你将能够：

快速掌握 Spring Boot 核心开发能力
构建完整的后端项目认知体系
实现从“入门”到“独立开发”的跃迁

就像“滚雪球”一样，知识不断积累、能力持续放大，实现指数级成长 🚀

最后，如果这篇文章对你有所帮助，帮忙给作者来个一键三连，关注、点赞、收藏，您的支持就是我坚持写作最大的动力。

同时欢迎大家关注技术号:「猿圈奇妙屋」，以便学习更多同类型的技术文章，免费白嫖最新BAT互联网公司面试题、4000G PDF编程电子书、简历模板、技术文章Markdown文档等海量资料。

ps：本文涉及所有源代码，均已上传至Gitee开源，供同学们直接对照学习 Gitee传送门，同时，原创开源不易，欢迎给个star🌟，想体验下被🌟的感jio，非常感谢❗

🫵 Who am I？

我是 bug菌，一名深耕 Java 后端领域数十年的一线研发老兵，曾担任独角兽企业后端技术经理、研发架构师等职位，长期专注于 Java 后端、分布式架构、微服务治理、高并发系统、工程效能与研发管理等方向。

目前活跃于多个主流技术社区，包括：

CSDN｜稀土掘金｜InfoQ｜51CTO｜华为云开发者社区｜阿里云开发者社区｜腾讯云开发者社区｜开源中国｜博客园｜墨天轮 等平台。

曾获得：

CSDN 博客之星 Top30
华为云多年度十佳博主 & 卓越贡献奖
掘金多年度人气作者 Top40
CSDN、掘金、InfoQ、51CTO 等平台签约作者 / 优质作者

截至目前，全网技术内容累计影响读者众多，全网粉丝已超过 30w+。

如果你也关注 Java 后端、架构设计、技术成长、职场进阶与研发管理，欢迎关注我的技术内容合集入口：👉 点击查看 👈️

硬核技术号 「猿圈奇妙屋」 期待你的加入。

这里不仅分享技术干货，也记录一线研发人的成长、踩坑、思考与进阶路径。

愿我们一起打怪升级，在技术路上持续进阶。

- End -

通义灵码不仅改名，还要收费了！！！

SimonKing — Wed, 27 May 2026 01:08:57 GMT

关注我的公众号：【编程朝花夕拾】，可获取首发内容。

01 引言

在更新IDEA的插件的时候，发现通义灵码竟然改名字了？

原以为只是改了名字，详细了解了之后，才发现免费版功能严重阉割，倒逼付费使用！

02 官方通知

从阿里云官网的公告了解到：2026年5月20日，"智能编码助手通义灵码"（Lingma）正式更名为 Qoder CN，并同步启用全新订阅定价方案和 Credits 配额机制。

通知地址：www.aliyun.com/notice/deta…

官方说明：help.aliyun.com/zh/lingma/p…

更名原本大可不必在意，但是免费版该功能阉割，这样广大使用的用户倍感不爽。

03 阉割了什么

官网表明，原来订阅通义灵码的用户依然保留有基本的权益，我们主要看看免费的版本的功能。

老版本免费版功能

新版本Qoder CN

现在的个人社区版：

代码生成：仅"有限的智能补全"
智能会话：仅 Chat Ask & Chat Agents（有限额度的模型对话）

免费版从"能用完整功能"变成"功能残血还限额度"，实质上是在强制推动免费用户转向付费。

04 存量客户安排

定价保护

2026年5月20日北京时间12:00前购买完毕的订阅，按原价格执行至合同到期
存量订阅到期后续费，按新版价格执行
存量订阅到期后新增席位，按新版价格执行

存量订阅切换新定价的代价

切换到新定价（启用 Credits 机制）后，可获得：

新增 GLM 5.1、DeepSeek V4 等模型选项
Quest、RepoWiki、Agent 会话、Subagent 不再限制次数
新增 Experts 专家团能力

05 小结

免费版实质性阉割，这似乎意味着薅羊毛时代正式终结；阿里从获客工具转向商业变现，企业订阅为核心利润来源。老铁们，你们还在用通义灵码么？

华为抛出“韬定律”：芯片竞争，终于不只盯着几纳米了

倔强的石头_ — Tue, 26 May 2026 10:41:34 GMT

这不是一句“绕开摩尔定律”的口号，而是把芯片进步的主指标，从“空间里还能塞多少晶体管”，换成“系统里还能少等多少时间”。

图注：华为何庭波在 ISCAS 2026 发表 “New Semiconductor Path in Practice / 半导体新路径探索与实践” 主旨演讲。图源：华为官网新闻稿。

01 这次刷屏的，不只是一个新名词

5月25日，上海，IEEE 国际电路与系统研讨会 ISCAS 2026 上，华为董事、半导体业务部总裁何庭波发表主旨演讲，提出了一个很容易刷屏的新词：韬(τ)定律。

我第一眼看到这个名字，也有点职业病式地警惕：技术行业最不缺的就是“新概念”。

但把华为新闻稿、ISCAS 议程，以及何庭波署名的 ChinaXiv 预印本放在一起看，这件事最值得讨论的地方，反而不是“又一个定律”四个字，而是它背后那个工程判断：

半导体行业不能再只靠把晶体管做小来讲增长故事了。

过去几十年，我们习惯用“几纳米”理解芯片。制程越先进，晶体管越小，密度越高，功耗和性能也跟着改善。摩尔定律给产业提供了一个极其清晰的节拍器，登纳德缩放也曾经让功耗、电压、尺寸之间的关系变得顺滑。

但这套叙事现在越来越贵，也越来越难。

先进制程的研发和设计成本高到吓人，互连的电阻、电容开始吞掉很多收益。晶体管继续变小，不再自动等于系统体验继续变好。

02 韬定律到底在讲什么

图注：从“几何缩微”到“时间缩微”的理解框架。

τ，本来就是电路里常见的“时间常数”符号。比如我们经常说 RC 延迟，本质上就是电阻 R 和电容 C 共同决定了信号响应需要多久。

华为这次把这个概念往上抽象了一层：不只看一个器件、一段导线，而是把器件、电路、芯片、系统里的等待时间，都放进同一个优化目标里。

换句话说，以前的主线是：

把空间缩小。

晶体管更小、线更短、面积更省。

而韬定律提出的主线是：

把时间压短。

信号传播更快，关键路径更短，访存和通信更少绕路，端到端任务更快完成。

这对互联网从业者其实很好理解。我们做一个复杂系统的性能优化，从来不会只盯一行代码。

一个接口慢，可能是 SQL 慢，可能是缓存没命中，可能是跨机房链路绕远了，也可能是上游服务的队列把请求堵住了。真正有效的优化，往往是把全链路的等待拆开，找到最主要的那段时间，然后一点点压缩。

韬定律讲的也是类似的事，只不过它发生在芯片和电子系统里。

03 它不是单点优化，而是跨层协同

图注：韬定律强调器件、电路、芯片、系统的跨层协同。

华为公开材料里，把这套方法放在几个层级里讨论。

器件层，继续优化晶体管和互连的电阻、电容，尽量减少底层时间常数。

电路层，引入 LogicFolding，也就是“逻辑折叠”。它的核心不是魔法，而是通过垂直堆叠等三维组织方式，把原本摊在平面上的部分关键路径折起来，缩短走线长度，降低 RC 延迟。何庭波预印本中提到，在移动 SoC 的案例里，LogicFolding 在固定器件节点上带来了晶体管密度和能效的提升。

芯片层，重点变成软件、架构、芯片的协同。很多时候，性能不是算力峰值不够，而是数据流、指令流、访存层级没有配合好。把真实负载拆开看，哪些时间花在计算，哪些花在搬数据，哪些花在同步，才有机会继续往下压。

系统层，华为提到灵衢总线、统一内存编址和原生内存语义。这里的关键词是“少转换、少拷贝、少握手”。AI 计算尤其典型：芯片之间、机柜之间、数据中心之间的通信越来越决定整体效率。单个芯片再强，如果大量时间都在等数据，系统吞吐也会被拉住。

所以，韬定律真正想强调的不是某一个器件参数，而是把全栈等待时间变成一个共同优化目标。

04 它重新定义了什么叫“先进”

我觉得这件事真正有意思的地方，是它把“先进”重新定义了一次。

以前我们问一颗芯片先进不先进，第一反应是制程节点。现在华为想说：如果你能在同样制程下，通过三维电路组织、架构协同、互联协议和系统设计，把关键等待大幅压短，那也是一种先进，而且可能是接下来更现实的一种先进。

这不是说制程不重要。

制程仍然重要，材料、光刻、晶体管结构也仍然重要。但它们不再是唯一答案。先进封装、3D 集成、片上网络、内存体系、光互联、系统软件，都会越来越像同一张牌桌上的玩家。

更直白一点说，后摩尔时代的竞争，不只是“谁能把芯片做得更小”，也会是“谁能把系统里的等待压得更少”。

05 也要冷静：它还不是被完全验证的自然定律

当然，冷静一点看，韬定律今天仍然更像一个产业方法论，而不是已经被全行业验证的自然定律。

首先，何庭波的论文目前是预印本。按照 ChinaXiv 的说明，预印本不等于已经完成严格同行评审。

其次，LogicFolding 要真正规模化，绕不开良率、散热、堆叠工艺、EDA 工具链、测试维修、供应链协同这些硬问题。

再其次，τ 是时间指标，不是能耗指标。一个系统如果跑得更快但耗电也等比例上升，那对手机续航和数据中心电力都不是好消息。

所以我不太想把它写成“摩尔定律终结，华为重新发明未来”这种标题。那样热闹，但不准确。

更准确的说法是：

当几何缩微的红利变薄以后，华为把自己的工程经验总结成了一个新的优化框架，并试图把全栈协同变成后摩尔时代的主线。

06 写在最后

这其实很符合今天的技术现实。

互联网、AI、云计算、芯片都在发生同一件事：单点优化越来越不够用了。真正的效率来自系统工程，来自跨层协同，来自把“看不见的等待”变成可度量、可压缩、可交易的指标。

韬定律能不能成为行业共识，还要看未来几年更多产品、更公开的数据、更广泛的生态验证。

但它至少提醒了我们一件事：

下一代芯片竞争，不只是纳米数的竞争，也会是时间管理能力的竞争。

谁能让信号少走弯路，让数据少等一会儿，让系统少做一次无谓的转换，谁就有机会在后摩尔时代多赢下一点点确定性。

而工程世界里，很多大变化，最初都是从这一点点确定性开始的。

零基础用AI写App？兄弟😂 醒醒吧，那只是个玩具罢了！

蝎子莱莱爱打怪 — Tue, 26 May 2026 07:43:23 GMT

本文要点：

AI会替代一部分初中级程序员，但替代不了真正有实力的工程师

零基础用AI写App只是玩具，真正的编程复杂度远超想象

程序员要从"写代码的人"升级为"驾驭AI的架构师"

附具体学习路线和我的IM项目真实案例

一、一个反直觉的现象

最近刷社交媒体，你一定见过这种类型的帖子或者评论：

"不会写代码，用AI一天做了个XX App，震惊！"

评论区一片"学编程没用了""会用AI就行了""未来程序员要被淘汰了"。

2025年初，OpenAI的联合创始人Andrej Karpathy提出了一个概念叫**"Vibe Coding"**——不写代码，靠感觉和自然语言指挥AI写。这个词迅速火遍全网，成了AI编程的代名词。不过连他自己后来都承认，AI生成的代码"can still be gross"——还是可能很烂。

听起来很美好，对吧？

但我想说一个可能让你不太舒服的观点：AI越强，越需要扎实的技术基础。不是不重要了，是比以往任何时候都重要！

AI只是把瓶颈从"写代码"转移到了"审代码"，从"执行"转移到了"决策"。以前你需要会写，现在你需要会驾驭。而驾驭的前提，是你真的懂。

二、"AI会替代程序员"——这句话对了一半

先说一个很多人不爱听的真相："AI会替代程序员"这句话太笼统了。 准确的说法是——AI会替代一部分初中级程序员，但替代不了真正有实力的工程师。

什么意思？

我们先看看AI现在能做什么。一个CRUD接口、一个增删改查页面、一个简单的数据展示列表——这些过去是初级程序员每天干的活。写一个Controller、配一个MyBatis的XML、调一个数据库查询、拼一个前端列表页。这种工作，AI现在干得比初级程序员更快、更准、还不用下班。

你说，如果一个程序员的核心价值就是"把需求翻译成代码"，那他跟AI有什么区别？区别只有一个——AI更快，不要工资，不请假。

所以这部分岗位，确实危险了。

但你要是说"AI要替代所有程序员"，那就是危言耸听了。因为编程这件事，远远不止"把需求翻译成代码"这么简单。

关于这个问题，业界其实早有共识（相关讨论）：

"Strong engineers are not valuable because they can type syntax. They are valuable because they understand problems, constraints, and trade-offs."

翻译过来就是：强工程师的价值不在于会敲代码，而在于理解问题、约束和权衡。

这些东西，AI目前做不到。

所以结论很清晰了：

只会写CRUD的初级程序员——危险，AI能干你的活
只会照搬框架模板的中级程序员——危险，AI也能干你的活
能做架构决策、能权衡技术选型、能排查疑难杂症的高级工程师——安全，AI是你的加速器

AI不会替代程序员这个行业，但会重新定义"什么样的程序员有价值"。 而这个"有价值"的标准，比以前更高了。

三、AI擅长0→1，但1→100还得靠你

AI确实厉害。给它一个Prompt，10分钟它能搭出一个看起来像模像样的应用。前端界面有了，后端接口有了，数据能存能取，点两下还真跑得起来。

但这只是0→1。

从"能跑的原型"到"能上线的真实产品"，中间的距离，比大多数人想象的要远得多。

AI做出来的东西，也许能跑，但"也许并不是你想要的"。它的理解跟你的意图之间，永远存在偏差——理解偏差、设计偏差、细节偏差。你以为它懂了，它其实只懂了个大概。

到了1→100的阶段：消息丢了怎么补？并发上来怎么扛？数据一致性怎么保证？跨服务器怎么路由？

你可能会说："这些问题我告诉AI，它也能处理啊。"

没错。但前提是——你得先知道有这些问题。

我拿一个具体的场景说明。假设你让AI帮你写一个"用户下单"的功能。如果你只是简单地说"帮我写一个下单接口"，AI很快给你生成代码——接收请求、检查库存、扣减库存、创建订单、返回结果。看起来没毛病，跑起来也没问题。

但如果你懂行，你知道下单远不止这些：

两个人同时下单，库存只有一件，会不会超卖？——并发问题
扣了库存但订单创建失败了，库存回不回滚？——事务一致性问题
订单创建成功了但消息通知发送失败了怎么办？——分布式事务问题
10000个人同时抢购，数据库能扛住吗？——性能问题
如果有恶意用户用脚本刷单呢？——安全问题

你知道这些问题的存在，你就能跟AI说："帮我写下单接口，需要处理并发超卖、保证事务一致性、考虑分布式事务、做限流防刷。"AI收到这个指令，大概率能给你一个不错的方案。

但如果你不知道"并发超卖"这个概念的存在呢？ 如果你从来没听过"分布式事务"这个词呢？你压根就不会想到要跟AI提这些要求。AI也不会主动提醒你——因为它不知道你不知道什么。

这就是问题的核心：不是AI不会，而是你不知道该让它做什么。

AI的能力没有上限，但你的知识储备决定了你能从AI那里拿到什么质量的输出。你的Prompt写得越精准、考虑得越全面，AI给你的结果就越好。而精准的Prompt，来自扎实的技术功底。

所以真正可怕的不是"AI写错了"，而是——你连AI漏了什么都看不出来，因为你自己就不知道那里应该有什么。

四、"我零基础用AI写了3个App"——我想说兄弟 😂 别闹了

现在社交媒体上到处是这种标题："不会写代码，用AI一天做了个XX"。

我直说：那只是玩具。

为什么？看下面这张图就明白了。零基础的人只看到水面上那10%——一个能跑的界面、几个功能按钮。而水面下真正的编程复杂度——并发安全、数据一致性、性能扩展、架构决策——他们压根看不到。

先说清楚，AI对普通人确实很有用。帮你整理Excel数据、生成PPT、写工作总结、处理图片、翻译文档、甚至做个简单的网页展示——这些场景AI表现得非常好。AI对普通人的意义就是提升工作效率，这个毋庸置疑。

但"提升工作效率"和"开发一个完整的商业化App"，中间的差距是数量级的。

Stack Overflow的官方博客讲过一个真实故事。他们的一位非技术编辑，用Bolt做了一款App。表面上10分钟搭出来了，界面还挺好看。但交给工程师一看——安全漏洞一堆、数据没有任何保护、代码混乱到无法维护、没有单元测试，甚至Redis是什么都不知道就已经在用了。

66%的开发者在使用AI工具时都遭遇过所谓的"生产力税"——AI生成的代码"几乎对但又不完全对"，你反而要花更多时间去修它。

你零基础用AI做的那个App，上线试试？用户数据要不要保护？并发扛不扛得住？支付接进去安不安全？做出来和能用是两回事，能用和能上线又是两回事。

所以别自嗨了。零基础用AI做App，发个朋友圈炫耀一下没问题，但别真以为自己会开发了。 因为前面说过的那些坑——并发安全、数据一致性、性能扩展、异常处理——你一个都不知道，AI也不会替你操心。

行外人觉得"AI编程很简单"，因为他们压根看不到水面下的冰山。

五、真实案例：一个IM系统到底有多复杂

说这些可能还是太抽象。我拿我自己做的项目举例。

我花了两年业余时间，一个人做了一个即时通讯系统——XZLL IM。Java微服务后端 + Flutter客户端，从零开始。

很多人觉得"做个聊天软件能有多难？不就是一个发送按钮一个消息列表吗？"

来，我列一下一个IM系统真正要解决的问题：

1. 消息可靠性

你发出的消息，对方一定要收到。不能丢，不能重复。听起来简单？这需要你理解TCP的三次握手、ACK确认机制、消息去重策略。消息发出去但网络断了怎么办？重试几次？重试期间对方收到了怎么办？幂等性怎么保证？

如果这些问题你回答不了，那你用AI写的聊天功能，大概率在弱网环境下就出bug了——而你连为什么出bug都不知道。

2. 高并发长连接

几万人同时在线，每人一个WebSocket长连接。操作系统告诉你：一个进程能开的文件描述符是有限的。怎么突破？需要理解Netty的Reactor线程模型，理解Boss Group和Worker Group怎么分工，理解Epoll和NIO的区别。

AI可以帮你生成Netty的启动代码，但它不会告诉你"你的线程模型在高并发下可能会阻塞"。只有你自己懂，才能提前规避。

3. 数据存储分层

用户和好友关系存MySQL，聊天记录存MongoDB，缓存和未读计数存Redis，消息搜索用Elasticsearch。为什么不用一个数据库搞定？因为每种数据库的特性和适用场景完全不同——这需要对存储引擎、索引原理、CAP理论有理解。

这个技术选型决策，AI做不了。它不了解你的读写比例、数据量级、查询模式。选型是架构师的事，不是AI的事。

4. 离线消息

用户下线了，发给他的消息怎么办？存哪？上线后怎么拉取？拉取的时候怎么保证不漏不重？我用Redis的ZSet按时间戳存储离线消息，上线后按时间范围拉取——这个设计决策，AI能帮你想出来吗？也许能，但前提是你得知道ZSet是什么、为什么用它、它有什么限制。

5. 跨服务器消息路由

用户A连接在服务器131上，用户B连接在服务器132上，A给B发消息怎么送达？需要一个gRPC的跨服务器转发机制。如果B同时登录了手机和电脑呢？多端同步怎么办？这些架构决策，不是AI帮你写几行代码就能解决的。

6. 群消息广播

一个群500人，一条消息要推给500个设备。500个人里有的在线有的离线，有的在一台服务器上有的分散在十台服务器上。不能一个人一个人地推，需要通过RocketMQ做消息广播，需要设计消息扇出策略——这背后是对消息队列、发布订阅模型的理解。

这还只是冰山一角。 还有Protobuf协议设计、JWT鉴权、API网关路由、MongoDB到Elasticsearch的数据同步、音视频通话的信令设计……

你说，这些是AI能帮你从0→1搞出来的吗？

也许它能帮你写出一些框架代码、生成一些CRUD接口。但每一个环节的设计决策、性能权衡、异常处理，都需要人有足够的知识储备。我在开发过程中也大量使用了AI工具（Claude Code、Cursor等）来加速编码，但核心的架构设计、消息流转路径、协议定义，全部基于我对底层技术的理解。

AI帮我写得更快，但不会帮我设计得更好。 设计，只能靠我自己。

六、程序员的角色转变：从"开发者"到"架构师"

所以结论来了：AI时代程序员不是要被淘汰，而是要升级。

什么意思？不是所有人都会失业，但所有人的角色都会变化。以前的程序员和未来的程序员，干的是不一样的事。

来看看前后的对比：

以前一个程序员的工作流：需求 → 设计 → 编码 → 测试 → 部署，大部分时间花在"编码"上。

现在呢？需求 → 架构设计 → 指挥AI编码 → 审查验证 → 调优。

编码的部分被AI加速了，但你的核心能力变成了三样东西：

1. 架构能力——系统怎么拆？模块怎么分？技术怎么选？用MySQL还是MongoDB？用HTTP还是gRPC？消息同步用推模式还是拉模式？这些决策AI做不了，因为它不理解你的业务、你的用户量、你的约束条件。

2. 验证能力——AI写的对不对？有没有安全隐患？性能能不能扛住？并发下会不会出问题？代码结构合不合理？你如果连TCP三次握手都说不清楚，怎么验证AI给你的网络方案？

3. 驾驭能力——怎么给AI精确的指令？怎么把一个复杂任务拆解成AI能处理的小任务？怎么在AI跑偏时及时纠正？这就像一个导演指挥演员——你不懂表演，你就导不了戏。

Google的资深工程师Addy Osmani说过一句话："Vibe Coding不等于AI辅助工程。前者是盲信AI的输出，后者是驾驭AI的能力。"

而这三种能力——架构能力、验证能力、驾驭能力——全部建立在扎实的技术基础之上。 没有基础，你就是个只会说"帮我写个App"的外行，而不是能驾驭AI的工程师。

打个比方：以前你是驾驶员，自己开车。现在你是车队策略师，AI是你的车手。车手负责执行，但你得比车手更懂赛道——才能制定正确的策略，才能在车手跑偏的时候把他拉回来。

你不需要亲手换每一个挡，但你必须知道什么时候该换挡。

七、哪些程序员会被淘汰？哪些不会？

说到这里，我想更直白地回答一个很多人关心的问题：到底谁会被淘汰？

画了一张分界图，一目了然：

先说会被淘汰的

1. 只会CRUD的"增删改查工程师"

如果你的日常工作就是：接到需求 → 打开IDE → 写一个Controller → 写一个Service → 写一个Mapper → 测试通过 → 提交代码。这种工作模式，AI现在就能替代80%。不是未来，是现在。

2. 不理解原理只会用框架的"调参侠"

会用Spring Boot，但不知道Spring的IoC容器是怎么工作的；会用Redis，但说不清Redis为什么快、什么场景该用什么数据结构；会用MQ，但不知道消息丢了怎么办。这种人，AI生成的代码跟他写的差不多，但AI快100倍。

3. 缺乏系统思维的"单点程序员"

只会写自己那一块代码，不理解上下游，不理解整个系统怎么运转。出了问题只能靠日志猜，猜不到就找大佬。这种人，AI也替代不了大佬，但能替代他。

再说不会被淘汰的

1. 能做架构决策的人

知道一个系统该怎么拆、技术该怎么做选型、性能瓶颈在哪、怎么横向扩展。这种能力不是AI能给的——它需要对业务的深刻理解和对技术的全局把控。

2. 能排查疑难杂症的人

线上CPU飙到100%怎么排查？消息队列积压了100万条消息怎么办？数据库死锁了怎么分析？这些问题，AI给你一段排查命令容易，但判断问题出在哪、该怎么做决策，需要经验和对底层原理的理解。

3. 能驾驭AI的人

知道怎么把一个复杂需求拆解成AI能理解的任务，知道AI生成的代码哪里可能有坑，知道什么时候该让AI干活、什么时候该自己动手。这种人，AI是他的倍增器。

看清这个分界线，就知道自己该往哪个方向努力了。

八、那到底该怎么做？程序员的学习路线

不是让你不用AI工具，而是：先用基础武装自己，再用AI放大能力。

那具体该学什么？我结合自己做IM项目的经历，按优先级列一个路线：

我画了一个学习路线金字塔：

第一层：计算机基础（最重要，别跳过）

这是所有编程能力的根基。没有这一层，上面盖什么都是空中楼阁。

网络原理（TCP/IP、HTTP、WebSocket）——我设计IM的消息传输方案时，如果不懂TCP的可靠性机制和WebSocket的全双工通信，根本无法做出合理的选择。AI可以帮你写Netty代码，但它不会告诉你"这个场景应该用WebSocket而不是HTTP轮询"。学了网络原理，你才能判断AI给你的网络方案对不对。

操作系统（进程/线程、内存管理、IO模型、Epoll）——高并发程序的本质是在跟操作系统打交道。你不懂IO多路复用，就理解不了Netty为什么快；不懂线程调度，就不知道线程池参数该怎么配；不懂内存模型，就排查不了内存泄漏。这些是AI写代码时的"隐形假设"，你不懂就发现不了。

数据结构与算法——不是让你去刷LeetCode应付面试，而是真正理解。知道B+树怎么工作的，才能理解MySQL索引为什么高效；知道哈希表的冲突处理，才能理解Redis的渐进式Rehash；知道图的遍历算法，才能设计消息路由策略。AI能帮你实现算法，但只有你理解了，才知道该让AI实现哪个算法。

第二层：数据库与存储（吃饭的家伙）

几乎所有程序都绕不开数据存储。

关系型数据库（索引原理、事务ACID、锁机制、隔离级别、慢查询优化）——IM系统里用户、好友、群组、会话全部存在MySQL。如果你不理解索引的B+树结构、事务的隔离级别、行锁和表锁的区别，你连AI生成的SQL有没有问题都看不出来。SQL写错了AI不会提醒你，但你线上数据出问题了那可是真金白银。

NoSQL（Redis数据结构与适用场景、MongoDB的文档模型、Elasticsearch的倒排索引）——IM系统用了MongoDB存消息、Redis做缓存和未读计数、Elasticsearch做搜索。每种存储用在哪里、为什么用它、它有什么限制——这些选型决策全是架构层面的，AI做不了。

第三层：并发与分布式（进阶必备）

这一层是区分"会写代码"和"会做工程"的分水岭。

并发编程（线程模型、锁机制、CAS、线程池、volatile）——万人在线的消息推送，如果不懂线程池的参数配置和锁的粒度控制，AI写出来的代码在并发场景下分分钟出bug——而你根本看不出问题在哪。并发bug是最难调试的bug，因为它不是每次都复现。

分布式系统（消息队列、RPC、服务发现、CAP理论、分布式事务）——IM系统涉及gRPC跨服务器通信、RocketMQ消息广播、Nacos服务注册发现。这些架构决策，AI能帮你写实现代码，但选型决策必须你自己做。

第四层：架构思维（高级方向）

这一层不是学出来的，是在前三层的基础上，通过实战项目练出来的。

怎么从需求推导出技术架构？
怎么评估一个方案的性能瓶颈？
怎么在多种技术方案之间做权衡取舍？
怎么设计一个可扩展、可维护的系统？

这些能力的培养没有捷径，只有一个办法：做真实项目。 不是做一个Todo List，而是做一个真正有复杂度的系统。比如一个IM系统、一个电商系统、一个推荐引擎——任何能让你面对"真实复杂度"的东西。

同时：学会驾驭AI工具

以上四层是基础，同时你要学会使用AI工具（Claude Code、Cursor、Copilot等），它们确实能极大提升效率。但永远保持对代码的理解和掌控——你不是在"让AI帮你写代码"，你是在"用AI加速你的想法落地"。

一句话：不懂代码，就无法真正驾驭AI。懂代码，AI就是你的倍增器。

九、一个新概念：Harness Engineering

说到这里，我想引出一个2026年正在快速升温的概念——Harness Engineering。

Google的资深工程师Addy Osmani在O'Reilly上发表过一篇文章，标题就叫《Agent Harness Engineering》。他还专门做了一个AI辅助工程的实践指南。他说了一句很关键的话：

"一个裸的AI模型不是Agent，Harness（驾驭装置）让它成为了Agent。"

什么意思？

就好比一匹千里马，它跑得再快，没有缰绳、马鞍、方向指引，你也骑不了。Harness Engineering就是这个缰绳和马鞍——它指的是围绕AI Agent设计的那套约束、反馈循环、验证机制和上下文管理。

具体来说，一个Harness包括：

约束设计：AI能做什么、不能做什么、边界在哪
上下文管理：给AI提供正确的项目背景、代码规范、架构约定
验证机制：AI生成的代码怎么验证对不对、跑测试、过Review
反馈循环：AI做错了怎么纠正、怎么让它从错误中学习
工具接口：AI能用哪些工具、怎么调用、权限怎么控制

你看出来了吗？这恰好就是这篇文章一直在说的"驾驭AI"的具体实践。

前面我说了，AI时代程序员的核心能力是架构能力、验证能力、驾驭能力。Harness Engineering就是这三样能力的工程化落地。它不是一句口号，而是一套可操作的方法论。

拿我自己做IM项目来说，我并不是简单地跟AI说"帮我写个IM系统"就完事了。我会先告诉它整个系统的架构分层——网关层负责鉴权路由，长连接层用Netty做WebSocket，业务层处理消息存储和好友关系，数据同步层消费MQ写ES。我会规定消息的Protobuf协议格式，约定Chat ID的生成规则，说明离线消息用Redis ZSet存储的策略。我会把一个复杂功能拆成十几步，让AI一步一步来，每一步都验证结果。

这个过程，本质上就是在给AI搭建一个Harness——告诉它约束是什么、上下文是什么、怎么验证做得对不对。

而这一切的前提是：我自己先搞懂了Netty的线程模型、Redis的数据结构、消息队列的投递语义、Protobuf的序列化原理。如果我不懂这些，我连Harness该约束什么都不知道。

你的基础越扎实，你的Harness就越精密，AI的输出就越可靠。

关于我是怎么在IM项目中从零搭建Harness、有哪些具体实践和踩过的坑，我会在下一篇文章中详细展开。

十、最后说几句掏心窝的话

这篇文章写到这里，我想回到一个最根本的问题：基础技术到底有多重要？

我用整篇文章在说这件事，但让我再总结一次：

AI能帮你写代码，但不能帮你理解代码。AI能帮你搭框架，但不能帮你做架构决策。AI能帮你快速出原型，但不能帮你把原型变成生产级产品。这些能力的背后，全部是基础——网络原理、操作系统、数据库、并发、分布式。没有这些，你跟AI之间的对话就只能是"帮我写个XX"，而不是"帮我实现这个架构方案，注意处理并发和事务"。

基础决定了你能从AI那里拿到什么质量的输出。 这就是为什么AI越强，越要学基础。

那程序员到底怎么避免被AI淘汰？

说难听点，路就两条：

第一条：死磕技术，往上走。 把基础打牢，从"写代码的人"升级为"做架构决策的人"。学会驾驭AI，让AI成为你的倍增器。这条路不难理解，但需要时间和汗水——没有捷径。

第二条：认清现实，趁早转行。 如果你既不想补基础，又不想升级能力，只想靠AI混日子——那说实话，趁早转行可能是更理性的选择。不是每个人都要当程序员，但如果你想留在这个行业，就必须提供AI提供不了的价值。温水煮青蛙，煮到最后是最惨的。

没有第三条路。 指望"AI替代不了我"是自欺欺人，指望"我会用AI就行了"是掩耳盗铃。

AI是一个放大器——放大高手的能力，也放大菜鸟的无知。基础扎实的人用AI，效率提升10倍；基础不牢的人用AI，只是把错误放大了10倍。

AI不会淘汰程序员，但会让不懂基础的"程序员"裸泳。

所以回到标题那句话：零基础用AI写App？醒醒吧，那只是个玩具罢了。

真正有价值的，不是你用AI做出了什么，而是你理解了多少。理解得越深，AI能帮你做的就越多。理解得越浅，AI只能帮你做玩具。

说完了技术和职业，最后我想说点题外话。

不管你是刚入行的新手，还是干了十几年的"程序大叔"，我想说一句：保持空杯心态。

AI这波变化来得太快，快到所有人都有点慌。新手慌"还要不要学"，老手慌"会不会被替代"。但你冷静想想，哪一轮技术革命不是这样？从汇编到高级语言，从单体到微服务，从手工部署到DevOps——每一次都有人喊"要完蛋了"，但每一次挺过来的人，都变得更强了。

这次也一样。AI不是洪水猛兽，它就是一波新的技术浪潮。你不需要比浪潮跑得快，你只需要站在对的方向上，别被冲走就行。

所以尽可能别焦虑。好好学你的基础，好好做你的项目，好好生活，保持一个好心态。技术这条路很长，不是百米冲刺，是马拉松。能跑到最后的，从来不是跑得最快的，而是心态最稳的。

普通程序员有没有必要学习 Agent 开发？

双越AI_club — Tue, 26 May 2026 01:59:38 GMT

大家好，我是双越。wangEditor 作者，前百度滴滴资深前端工程师，慕课网金牌讲师，PMP，前端面试派作者。

我正致力于两个项目的开发和升级，感兴趣的可以私信我，加入项目小组。

【划水AI】 Node 全栈 AIGC 知识库，包括 AI 写作、多人协同编辑。复杂业务，真实上线。
【智语】 AI Agent 智能体项目。一个智能面试官，可以优化简历、模拟面试、解答题目等。

“人人都用 AI ，我们需要更懂 AI 的人” —— 这将是未来所有招聘岗位的要求之一

开始

从 2025 年 agent 就开始流行了，当时是因为 MCP 协议推广，让 agent 扩展第三方能力。

后来 Skills 推广开来，让大家看到了 AI + skills 就可以成为领域专家，深入到各个垂类。

再到 2026 年春天，OpenClaw 小龙虾突然火爆网络，再后来 hermes 出现要代替 Openclaw 。

以及 claude code 源码泄漏，大家了解了它内部的结构，还有现在 codex 正在推广使用。

2026 年是 agent 最火爆的一年，全世界都在开发用 agent ，也都在开发 agent 。

问题来了：作为普通程序员，我们肯定都用 agent ，至少 AI 编程吗。但我们有没有必要深入学习 AI Agent 呢？

答案当然是肯定的。

可以更好的使用 Agent

无论任何领域，使用任何工具和技术，你知道它的原理和设计，才能更好的使用它。

例如我知道一位同学，使用 Cursor 编程，一个聊天一直用，他本能的觉得这样有上下文更多信息，AI 可能会回答的更好。但其实这样更容易造成上下文污染，更容易让 AI 产生幻觉？

这是 Agent 核心模块之一：Context 上下文管理和压缩。

还有 Claude Code 或者 Cursor 提供了很多高级技巧，例如 subagent hooks 等，你会本能的抗拒它们，因为不熟悉。只会配置一些 skills

如果你详细学习过 harness 工程的，对这些概念和模块就自然熟悉了，不用也知道它们是干嘛的。

你担心 AI 写的代码不安全，其实熟悉 agent 设计以后，你就会明白：agent 内部有严格的权限和安全机制。而且你可以设置 prompt 让它来写单元测试，达到某个测试标准。

这就像当年前端面试考源码一样，Vue React 都会用，但熟悉源码的人会用的更好。虽然你作为候选人抱怨内卷，但如果你是面试官，你也会考源码。

有机会转型 AI 工程师

看看你现在用的所有网站、软件、app ，哪个都有一个 AI 接口，什么 AI 搜索、AI 总结等等。

应用场景多，肯定会带来专业的开发岗位。现在 AI 工程师的招聘岗位已经很多了，而且会逐步增加。

当然，不是说所有的人都去转型做 AI 工程师，这毕竟是一部分开发岗位，大部分程序员还是该干啥干啥。

就像当年的小程序，各个公司都需要开发自己的小程序，就会催生很多招聘需求，但不是所有的人都去做小程序。

但是，早期加入的人都会吃到最大的红利，会以最低的要求、最高的工资入职，还有最好的晋升机会。

对于前端开发者

虽然 AI 编程的普及和 LLM 的进化，纯前端开发人员一定会慢慢消失。

因为绝大部分前端界面，AI 编程可以快速实现，后端人员一样能干。而后端的一些逻辑和数据，AI 不一定能完全搞懂。在 AI 编程的加持下，前后端还是有很大区别的。

所以无论是前端还是后端，大部分都会转型全栈开发。后端好转，前端不好转，有些前端开发者连 HTTP 协议都还没搞明白。

想要有好的竞争力，除了转型全栈开发，及早去搞 Agent 开发也是一个不错的选择。

最后

不要说我贩卖焦虑，你我都是人在江湖，冷暖自知。焦虑不焦虑的，看自己感觉，别光信我说的。

“人人都用 AI ，我们需要更懂 AI 的人” —— 这将是未来招聘程序员的要求之一。

Codex 把我家烂网给优化后，我 TM 直接原地起飞了。

cxuanAI — Mon, 25 May 2026 10:46:11 GMT

昨天看到一个非常有意思的事情，有人研究了一下用 Codex 直接把家里网络修复了一下，修复之后的网络直接原地起飞，实测速度堪比光速。

这本来没啥可说的。

但后面有意思的是，另外一个网友直接把原贴扔给了 Codex ，随后附上了自己的 prompt

Hey my friend says he improved his internet speed and here is what happened. Can you check if there are any improvements we can make for our internet? My provider says they're sending 1.2k gbps and anything I get is a result of hardware. I'm getting 55mbps right now pls fix make no mistakes.

这句话的意思是说。

我朋友说他的网速提高了，情况是这样的。你能帮我看看我们家的网络有什么可以改进的地方吗？我的网络供应商说他们提供的带宽是 1.2k Gbps，而我实际的网速是硬件问题导致的。我现在只有 55Mbps，请帮我解决这个问题，别出任何差错。

然后放了一下优化前和优化后的实测对比图。

这哥们的聪明之处在于，他直接把“别人成功优化的真实案例”当作上下文喂给 Codex，让 Codex 参考那个案例，给自己当前的烂网速做针对性诊断和修复。

也就是说，只要有人从 0 -> 1 真实跑通一个案例，你发出来之后其他人就可以很方便的裂变，变成 1 -> N。

这里我有个问题，为什么这个人的成功经验不是直接让 LLM 来直接回答呢（手动狗头）

然后 x 上确实有很多人通过这种方式优化了网络性能。

我自己也根据这个 prompt 进行了实操，确实网络直接原地起飞了。一条要求 Codex 针对网速改善的对比的请求，工作了 25s 就完成了。

然后这是优化之后的直观对比。

看起来效果提升的并不是特别明显，但我从用户亲身体验的角度来说，确实达到了直接原地起飞的效果。

要知道，我肉身是在国内。。。。。。

使用这种方式记得有一点，先评估再进行操作，先让 LLM 做好执行备份。否则容易把你的 xx 给直接 kill 掉。

比如这个哥们的操作就直接给我笑麻了。

我自己实测的过程中也出现过 codex 乱杀的情况，但是幸好我这个影响不太大。

直接给出大家 prompt 好了，你可以直接去 agent 上（任何 LLM 都可以尝试）进行修复。

诊断问题：首先运行了 speedtest-cli。
> 检查了 DNS 解析时间，
> 检查了 MTU、数据包丢失、Wi-Fi 信号/干扰。
> 发现了 3 个问题。
> 删除了过期的网络位置/配置文件。
> 终止或限制了占用带宽的后台进程。
> 优化了 mDNS。
> 运行了前后速度测试和延迟检查。

有人使用 /goal 命令直接修复，我没有使用 /goal 命令，不过修复的也不错。

希望大家都能体会到网速起飞的酥麻感，简直太爽了。

3.9元搞定Codex！国内也能畅用~（附教程，超简单）

AI袋鼠帝 — Mon, 25 May 2026 07:02:16 GMT

大家好，我是袋鼠帝。

我发现，最近很多朋友貌似都把自己的主力Agent换成了Codex。

我也不例外，Codex现在也是我的主力Agent。

因为最近Codex更新了几个版本之后，干活真的丝滑了很多，布置一个多步骤的复杂任务给它，基本上不用我中途救场，干活嘎嘎好用，稳得一批。

比如全自动操控浏览器帮我申请YouTube API Key、根据一套Skills完成产品宣传片，基本上都能一次性搞定，而且完成质量还挺高。

但从评论区，以及一些朋友的私聊中，我发现有个问题是：Codex对国内小伙伴来说，使用门槛还是高了。

魔法上网、注册、跨境支付、短信验证、API配置……一整套从0搞下来，光是门槛就足以把90%的人拦在门外。

我的评论区和私聊，几乎每周都有人在问这些问题。

还有一个问题是，我Codex便开了一个月20美元的Plus，额度也是很快就会用完。

我之前试过猛用一天，额度就没了。后面不得已，直接开了100美元一个月的Pro，还是挺肉疼的💸

不过最近我发现一个邪修办法，最低3.9元就能畅用Codex一个月。

实现原理

首先Codex是可以配置接入别的模型的，所以这个方案，我们就不用官方的，直接给Codex接入其他模型。

然后就是找一个便宜的Coding Plan套餐~

找了一圈，发现讯飞星辰的Coding Plan最便宜。最低只要3.9元/月，而且居然还是不限量。

缺点是模型选择有点少，只有5种，但3.9元一个月，一瓶饮料的钱，还要啥自行车🚲

而且配置好后，还可以在讯飞星辰的控制台随意切换模型，生效时间在2分钟左右。这点还是挺方便的。

怎么配置

本来我以为，只需要通过CC-Switch配置一下，就能简单搞定了，结果我错了。

简单配置的结果是Codex疯狂报错。

然后我就采用了增加一个适配器的方案，折腾一番之后，最终还是跑通了。

虽然整个过程还是要费点功夫，不过别担心，我已经把所有步骤封装成了一键脚本，傻瓜式操作。

现在只需要一行命令，就可以完成全部配置。而且随时可以切换回Codex的官方登录，点一下就搞定，巨方便。

为什么要用适配器

讯飞Coding Plan提供的是OpenAI兼容接口，但它当前更稳定可用的是 Chat Completions 接口。

而Codex现在主要走 OpenAI Responses API 。直接把讯飞接口配置进CC-Switch后，可能会出现：

stream disconnected before completion
response failed event received

主要是接口协议不完全匹配。

所以这里采用一个本地适配器方案：
Codex → 本地适配器 → 讯飞Coding Plan

适配器负责把Codex发出的Responses API请求，转换成讯飞能稳定处理的Chat Completions请求，再把结果转回Codex能识别的格式。

期待讯飞能尽快适配Codex啊
当然，它目前也能够，丝滑接入Claude、Cursor、Claude Code、Open Devin等Agent。

脚本做了什么

安装脚本会在本机启动一个只监听本地的服务： http://127.0.0.1:8666
它不会开放公网端口，也不会影响系统代理。

脚本会自动完成这些事：

1. 安装本地适配器
2. 在开机/登录后自动启动适配器
3. 在CC-Switch里新增一个独立配置：Xunfei Astron Adapter
4. 自动切换Codex到这个配置
5. 输入你自己的讯飞Coding Plan API Key
6. 保留原来的OpenAI Official配置，方便随时切回

使用前准备

你需要先做好这些准备：
1. 已安装CC Switch（Github搜索安装），76k的开源项目 2. 已经打开过一次CC Switch
3. 已安装Codex
4. 已有讯飞星辰的Coding Plan，并拿到API Key

5. Windows用户需要先安装Python 3

获取API Key的方式很简单，在讯飞星辰的Coding Plan订阅页面，直接复制就好。

macOS执行

国内用户可执行的脚本：

plaintext

curl -fsSL gitee.com/kangarookin… | bash

执行后，根据提示粘贴你的讯飞API Key。输入时不会显示明文，这是正常的。执行完成后，重启Codex。

卸载指令

plaintext

curl -fsSL gitee.com/kangarookin… | bash

卸载会移除本地适配器和后台启动项。如果当前Codex仍然指向适配器，脚本会尝试切回CC Switch里的其他Codex配置。

Windows执行

注意：因为我还在出差，手里没有Windows，所以Windows的脚本没有验证过。大家慎用。Mac的版本我亲自验证过，是ok的。

打开PowerShell，执行：

plaintext

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm gitee.com/kangarookin… | iex"

执行后，根据提示粘贴你的API Key，安装完成后，重启Codex。

卸载指令

plaintext

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm gitee.com/kangarookin… | iex"

Codex换上CodingPlan后，干活怎么样

配置搞完了，最关键的问题来了：换上国内模型之后，Codex干活到底行不行？

我用它跑了一下我的 ai-trend-search Skill ，让它帮我去X上搜今天的AI领域热点选题。

看看这个执行过程：它先读了skill，发现有ai-trend-search skill，然后查看了Skill的详细内容，接着自动运行雷达模式去搜索。

整个执行过程跟用GPT-5.5的时候几乎一模一样，完全自主。

最终结果：8个信源全部正常扫描，120条原始信号里精选出4个高价值选题。

而且思考过程都会展示出来，感觉跟在Codex用GPT-5.5的交互几乎无感切换。

不过执行更复杂的任务应该还是搭配GPT-5.5更好，毕竟原汤化原食嘛😆

说实话，我本来以为换成3.9元的国内模型，体验肯定会打折扣。但实际跑下来，日常任务完全够用，而且不太担心额度的问题。

感兴趣的朋友可以去试试👇

套餐档位

除了3.9元首月套餐外，还有另外两档套餐，可选择的模型更多，也更强：

专业版 39元/月：模型包含GLM-5.1、MiniMax-M2.5、KIMI-K2.5、DeepSeek-V3.2等
高效版 199元/月：重度玩家顶配，额度充足

都是国产顶级模型了。
用量也更充裕，如果是重度玩家可以上199/月的高效版。
如果只是大量处理一些简单任务，用3.9元的最合适。

提醒一点：3.9元为首月优惠

如果是用来编程，这里面我最推荐GLM-5.1，编程能力超强。

比如我用Codex + GLM-5.1生成我的世界网页版，一次性就能生成的效果就很棒~

一般拿到一个模型我都会用这个Case来快速检测它的编程能力。

这效果，这流畅度，也侧面反映了，CodingPlan里面的GLM-5.1绝对正宗~

因为就连Deepseek v4都跑不好这个Case，跑出来贼多bug，就直接都穿模了..

对了，目前讯飞新人还可以获得新礼包卡奖励，双方都有，挺不错的。

我是袋鼠帝，一个致力于帮你把AI变成生产力的博主。
我们下期见~

能看到这里的都是凤毛麟角的存在！
如果觉得不错，随手点个赞、在看、转发三连吧✨
如果想第一时间收到推送，也可以给我个星标⭐

谢谢你耐心看完我的文章～

体验完阿里首款Design Agent，我开始替UI/前端焦虑了..

AI袋鼠帝 — Mon, 25 May 2026 06:31:04 GMT

大家好，我是袋鼠帝。

作为一名后端程序员，我略懂前端，但是对于UI设计是一窍不通。

还记得以前上班的时候，公司大部分UI设计都是妹子，我连Figma都没打开过。

自从AI快速发展起来以后，我虽然能做出各种功能复杂的前端的项目，但一直以来有个问题困扰我：做不好看。

我能分辨什么样的页面是高级的、漂亮的，但我就是很难做出那种高级感、带交互动效的页面。这种感觉很难受😮‍💨

本来我还想去学一下UI设计和Figma的，但一直没时间。

然后...我就又一次体会到了什么叫只要你学的慢，就可以不用学。不得不说，这句话还是有一定的道理。

当然，我不鼓励大家一直不学，毕竟学了，你至少知道这玩意儿是怎么发展的，底层逻辑是什么。

先给大家看个好玩的，这是我20分钟左右快速做出来的一个产品官网页面。

效果是不是还不错？我感觉这直接比很多产品的官网都要好了吧。

整个页面的设计就很舒服，然后各种动效，用户可以交互，效果是很炸裂。关键是，这是一个不会UI设计的后端程序员做出来的（正是在下）。

大家一定很好奇，这个效果，是怎么做到的？

不卖关子，是**QoderWork的AI Native设计工作台（Design Desk）**帮忙做的，简单来说，它是一个设计Agent。

Design Desk还真是让我挺惊艳的，我使用的整个过程非常顺手，即便过程中遇到一些问题，不管是对页面哪部分设计不满意，还是一些细节（颜色、边框、间距），都能在画布上手动快速调整。

而且整个开发流程，对于不熟悉软件开发但是有自己想法想要快速折腾出效果的人非常友好（后面会详说）。

做产品官网

比如开头展示的产品官网，我给了它一个Prompt：

为一家音响公司打造产品网站。使用React、Tailwind CSS和Framer Motion实现所有动画。产品本身是一件雕塑一样呈现的。声音要通过交互来可视化，而不是单调的虚头。材质和工程设计要通过滚动来展现。即使在静态状态下，网站的使用也应该流畅、滚动丝滑流畅。每个交互元素都要有微交互。网站要完全响应式。参考案例：Transparent Speaker、Bang & Olufsen、Sennos、Tecno、Awwards级别。

第一版效果就已经很不错了。

然后我给QoderWork加入了图片转3D的Skill：tripo-3d-generation。

在使用GPT-image2设计好产品图之后，让QoderWork直接转成3D产品，并替换到网页中。

最终效果相当nice。

说实话，以前一直做的后端程序员，我从来没想到有一天我能做出看起来这么专业的产品官网（感觉已经比很多产品官网都要高级了）。毕竟我不是前端，更不是设计师。

而且仅仅只花了20分钟。关键我都没怎么动手，只是做了几道选择题（在一些关键节点做决策就行了）。

然后我还对比了一下Codex，我用同样的提示词给Codex，它生成的效果虽然也还不错，但也能够明显看出是不如QoderWork Design Desk的。

看来专业的事还得专业Agent来做🤝

物理实验3D模型

最近X上生成教育相关的3D模型网站非常火。

然后我就顺便用QoderWork做了个高中物理实验3D交互网站。

顺便看看，对于不熟悉软件开发、但有自己想法的人，QoderWork到底友不友好。

我的输入很简单：

帮我设计一个用于高中教学互动的3D交互实验室的科学App，重点是3D模型可以互动，演示高中物理不同磁学、原子物理部分，展示一些物理的不同原理。然后全局扩展。

注意，这段话完全没有任何软件开发的术语，不需要你有开发思维，也不需要你给它具体的实现方案。

然后它做了一件让我觉得聪明的事，没有直接开始干活，先是追问了几个问题，帮我深挖更具体的需求。

问完之后也没有胡乱开始写代码，是生成了一份设计计划让我确认。

这份计划包含交付的产物、技术方案确认、页面、交互设计以及风险评估。还挺详细的。
这个流程我觉得是对的。先对齐、再计划、最后执行。

方向对齐在前，执行在后，这样一次命中率就高很多，不用反复重来。也是让Agent生成质量更稳的关键。

最后生成的是带3D交互的完整的React + Vite前端工程文件。

这一点跟Claude Design不一样，据我所知Claude目前只能出HTML。

QoderWork则可以直接输出完整工程文件，这对于一个项目的维护和迭代来说很重要。

我让我的前端朋友打开了几个文件看了一下，他的评价就是确实不错，确实符合大部分前端工程师的编写习惯。

所以我觉得QoderWork的design desk对于不懂开发的人来说，也很友好。

不需要你懂一些技术术语，它会帮你挖需求、出计划。门槛比我预期的低很多。

当然，它只是拉高了所有人在做UI设计、前端的下限，对于专业的UI设计来说，他们用Design Desk的上限肯定会更高。

然后在整个体验中，有三个点让我觉得效率提升明显：

1. 画布上直接改：整个工程在无限画布上，基础的宽高、位置、拖拽、调整，不用写代码，实时生效。 2.框选修改：以前修改页面某块内容，大多要在对话框用文字描述导航栏左上角的那个按钮颜色改一下...
费劲巴拉打一堆字，关键有时候你还真不好描述。现在直接在画布上框选目标内容，告诉它你要怎么改就行。

3. 关键设计决策：做着做着发现需要换主题颜色、换字体这些全局性的东西，正常还是通过对话框改，然后等结果，而且改全局的东西还容易把代码改崩。
QoderWork现在把配色、间距、圆角、字号这些高频微调项直接以可调参数暴露出来，拖拽调整，实时生效，甚至不需要刷新就能看到效果。

还是那句话，不用等。

这三个点加起来，解决了同一个核心痛点：别让我等，别让我打字描述，在开发完成之后，需要的是简单，快速，精准的去调整页面。

不得不说QoderWork跟之前腾讯做的Figma类云端设计工具还是有本质的区别。

腾讯的核心还是在云端协作的矢量设计上。

QoderWork的定位是原生的AI驱动设计即代码工具：传统的"纯画图设计师"和"纯写页面前端"的界限正在坍塌，设计文件将不再是不可触碰的黑盒，而是团队所有人都可以共同维护的视觉资产。

另外QoderWork还内置了150多个高品质风格参考，有模板的好处是风格对人可控，解决了我一直以来的痛：有审美但做不出来。

极限测试：复刻天花板级网站

为了测试它的极限，我找了一个动效审美都是天花板的网站 lusion.co

真的，这绝对是我这辈子见过最炫酷的网站，没有之一，可以用震撼来形容。

这个网站的交互简直就像在看好莱坞大片，每一页翻动都伴随着极其复杂、丝滑又酷炫的3D变换。

这绝对是极限测试了。我敢说，目前不可能有任何AI能一次性百分百复现这个网站的前端。

1月份的时候，我丢给过Kimi的Agent，它能复刻出大约30%。

但是这次QoderWork生成的，很惊艳，我觉得到50%了。

可惜的是QoderWork目前没有视觉能力，lusion.co的录屏没法给它看，所以在理解上可能有一定偏差。

另外说下问题，目前Qoderwork在处理特别复杂的3D场景和连续滚动动效时，偶尔会有些卡顿，生成的代码也不是每次都能一跑就通，有时候需要手动调一下。

不过这才是第一个版本，这个程度还不错了。

顺带一提

QoderWork自定义工作台，除了设计工作台，还有PPT工作台、写作工作台。

PPT工作台每一页演示稿是独立HTML文件，内置各种中文字体，断网也能渲染。全流程有11个阶段，每个阶段用户都能介入。生成的效果，我试了一下，还挺好的，已经赶上臧师傅开源的PPT skill了。

写作工作台的选中即批注还挺有意思的，可以像审稿一样圈出某段文字，写下改得更正式、压缩到100字以内，AI就能围绕选中文本定向修改。

这两个先mark住，如果大家感兴趣的话，后续可以单独聊聊。

「最后」

这次尝试，我觉得我“做不好看”这件事，真的被解决了一大半。

以及我个人觉得，UI和前端确实越来越危险了，不知道UI和前端们怎么看，欢迎评论区交流。

我这么说不是没有依据。特别是现在我做OPC，从我个人的角度来说，如果我自己都能做出这样的产品官网，我为什么还要请专业的UI和前端呢？

因为目前做出来的效果已经比市面上很多产品的官网效果要好了。

前几天在北京的时候，跟一位老乡朋友吃饭聊天。她是在北京做了很久的资深律师，她主动聊起她焦虑，并问我有没有什么破局的方法。

我当时给出的破局办法有两种：

1. 打穿并放大：拥抱趋势，拥抱变化，深度使用AI。不仅要是行业的专家，更要成为行业+AI的专家。
2. 把自己变成更稀缺的人才：当一个人既能又能的时候，它的稀缺性是指数上升的。比如一个人，既懂AI的关键技术，又懂营销、有网感，还会商务（没模板也干），这样的人是非常稀缺的。所以说你每加一项技能，你的竞争对手就会少非常多，你就越稀缺，越有价值。

这也是我为什么一直没有找到我公众号的技术编辑的原因——因为适合帮我公众号内容的人太少太少了。

说真的，从Sketch到Figma，设计与研发格式不同的矛盾还在，原来传统工作页面，设计到代码的还原度平均不足70%，页面交互衔接中往往需要经历3-5轮的标注与返工。懂得都懂，真的太痛了。

以前的前端开发流程都是产品确定原型图，UI设计师出图，前端再画图。中间有多少沟通成本、多少开发周期。而现在借助design agent可能就是几句的事，输入自然语言，你就能得到可交付的工程文件。

所以，如果你对网页呈现的效果有一定追求，或者想优化团队现有的开发流程，可以去尝试一下QoderWork Design Desk这样的设计Agent。它确实是能提高审美、提高效率的生产力工具。

最后，希望评论区不要再说我贩卖焦虑了。因为AI的发展太快了，就连我自己也非常焦虑。

但焦虑是正常的。关键看你怎么对待它——采取行动，还是放任不管，都在于你自己。

不过，我家两代人的经历告诉我，人不能一直低头拉车，还得抬头看路。

能看到这里的都是凤毛麟角的存在！

如果觉得不错，随手点个赞、在看、转发三连吧✨

如果想第一时间收到推送，也可以给我个星标⭐

谢谢你耐心看完我的文章～

面试官：AI生成到90%突然断了，你的解决方案是什么？（万字长文深度剖析）

徐小夕 — Mon, 25 May 2026 06:04:45 GMT

最近遇到一个的粉丝，问了一个问题：

总结成一句话就是：

AI生成到90%突然断了，你的恢复方案是什么？

这个问题其实在AI技术面试中经常被问到，也是一个“看似简单，实则深奥”的问题。

如果大家的AI产品也遇到过以下问题，这篇文章将会非常有帮助：

用户网络波动（比如断网，网速时慢时快），WiFi 自动降级导致AI项目的流式输出中断
浏览器标签页被误关，重新打开后对话记录还在，但刚才那轮生成的内容丢失了
长任务生成到一半，服务端负载过高触发自动扩容，连接被重置
用户主动刷新页面，想保存刚才的内容，数据却丢失了

流式生成的核心价值是"快"，但如果"快"伴随着不稳定（不可靠），用户体验就会从"惊艳"变成"崩溃"。

所以作为优秀的产品经理和AI产品开发者，为了打造最好的用户体验，这一“关”，我们必须攻克。

接下来我就站在面试官的角度，系统的分析这个问题，并提供一个专业，可实操作，可落地的解决方案。

一个底层的背景：为什么流式生成天生脆弱？

要想深度理解“AI生成中断”问题的重要性，我们需要了解传统流式架构的几个痛点：

1. 纯内存状态：一断全丢

标准的 SSE（Server-Sent Events）或 WebSocket 流式架构中，生成状态通常只存在于如下图所示三个位置：

这三层全是易失性存储。 任何一层断裂，状态就彻底消失。

更复杂的问题是，LLM 生成具有强烈的顺序依赖性——第100个token的生成依赖前99个token的上下文，你无法像下载文件那样"从中间开始"。

2. 大模型的"不可重入"性（可以说是痛中之痛了）

这里给大家分享一个反直觉的事实：大多数AI生成请求不是幂等的。

即使我们把用户的 Prompt 原封不动再发一次，由于大模型的温度参数和采样的随机性，会导致第二次生成的结果和第一次完全不同。

这意味着"重新生成"不是"恢复"，而是"替换"。

对于长文本生成、代码生成、报告撰写这类场景，用户往往对第一次生成的“中间态”已经有了认知预期（ 可能已经读了一半，认为AI中断后继续生成，应该按照中断之前的内容继续生成，如果替换，等于否定用户的Tokens）

3. 业务成本的损耗

从商业角度看，一次中断的代价远不止用户体验，还包含如下成本投入：

算力浪费：生成到90%中断，这90%的token消耗已经产生成本，但用户没看到结果（不过主流的AI产品貌似做了一下平权优化）
上下文窗口浪费：恢复时如果从头重传历史消息，会快速吃掉宝贵的上下文长度
用户流失：我们内部AI产品的数据统计表明，一次"长生成中断"的用户，7日留存率下降约20%（太痛了）

综合上面的分析，其实结论已经很清晰了：流式生成必须像视频播放一样支持"断点续传"。

第一问：宏观思路——如果让你一句话概括解决方案，你会怎么说？

面试官："如果让你用一句话概括你的“AI中断恢复”的实现思路，你会怎么做？"

答："我会让生成过程像视频播放一样支持断点续传——核心是在生成过程中持续'落盘'状态，而不是等到结束才保存。"

面试官："具体怎么落盘？"

答："我设计了一个三层状态恢复模型：

客户端缓存层：SessionStorage 做热缓存，IndexedDB 做持久缓存，页面刷新后先让用户直接看到上一次已经生成的内容；
网关缓冲层：负责连接状态路由、心跳检测、区分'网络抖动'和'真正中断'；
服务端持久层：Redis 保存热生成状态（包括了 KV Cache），然后数据库做长期归档。

三层之间通过 checkpoint_id + offset + hash 三元组串联，确保恢复时的幂等性和数据一致性。"

同时在实现方案时，需要遵循如下几个实现原则：

1. 渐进式持久化

不要等到生成结束才保存。每生成一个"逻辑段落"（比如每512个token或每个自然段落结束），就触发一次状态快照。这样的好处是：即使对话中断，丢失的也只是最后一个段落，而不是全部。

2. 客户端是第一恢复“数据源”

建议优先从客户端的缓存中恢复已接收内容，实现"所见即所得"的视觉反馈，服务端只需补充"未接收的部分"。（当然也可以从统一服务端缓存层进行持久化兜底）

3. 幂等性设计（面试必备术语，用于“装”那啥）

通过 request_id + checkpoint_id + offset 三元组，确保同一恢复请求永远产生确定性的续传结果。

好啊，下面继续深入技术实现。

第二问：架构深挖——服务端怎么知道该从哪恢复呢？

面试官："用户刷新页面后，客户端发了一个恢复请求过来。服务端如何判断'这个请求是要续传'，而不是'新请求'？"

答："靠断点标记协议。我在 SSE 的每个数据包里都嵌入了 checkpoint 元信息，代码案例如下：

客户端在每次收到 chunk 时，都会把这个 checkpoint 存到本地。恢复时，在请求头（headers）中带上如下信息（标识）：

X-Checkpoint-ID: 本次生成的唯一标识
X-Client-Offset: 客户端最后收到的token数
X-Content-Hash: 本地缓存内容的校验和

服务端收到 Headers 中的标识信息后，会先去 Redis 查这个 checkpoint_id。如果存在，说明生成状态还在有效期内，可以进入续传流程。"

面试官："那如果客户端缓存损坏了，hash 校验不通过，又该怎么处理呢？"

答："那就退回到上一个可靠的 checkpoint 重新发送，而不是盲目续传。宁愿多传一点重复内容，也不能让恢复后的内容出现断层或乱码。"

第三问（状态机设计）：AI生成到一半，突然断了，服务端的状态该怎么处理？

面试官："连接断开的那一时刻，LLM 可能还在推理，这个时候是直接停止生成，还是有其他更好的方案呢？"

答："不用停止生成，这正是最容易踩坑的地方。我设计了一个六状态生成状态机：

状态转换的规则如下：

具体分享一下我的思路：

首先，当网关层检测到连接中断（连续3次心跳丢失）时，我们需要做的不是销毁状态，而是把状态机切到 PAUSED（暂停）。此时需要做的是：

冻结生成上下文：把当前的 messages、past_key_values（KV Cache）、已输出token序列做序列化；
写入Redis：SETEX generation:chk_xxx 3600，TTL设1小时；
异步归档：同时写入数据库（持久化备份，企业级必备意识），保留3-7天，防止Redis淘汰。

核心设计价值在于：在'网络抖动'阶段（心跳延迟>2秒）就进入'预暂停'，提前冻结。 因为 LLM 推理一直在消耗算力，如果等确认断连再冻结，可能已经有大量新生成内容送不到客户端，造成算力浪费。"

面试官："Redis 挂了又该怎么办？" （可见面试官被企业问题折磨的不轻）

答："Redis 是热存储，挂了就从数据库冷存储恢复。虽然延迟相对高一些（几十毫秒到几百毫秒），但至少不会丢状态。另一方面，我对 KV Cache 做了 INT8 量化压缩，能减少 70% 的 Redis 内存占用，避免高峰期 OOM。"

Good，我们继续下一个刁钻的技术面。

第四问：客户端策略——页面刷新了，用户凭什么能看到旧内容？

面试官："用户刷新页面，浏览器内存全清空了，你凭什么让用户立即看到之前的内容？"

答："靠客户端双保险缓存，具体的实现代码如下：

恢复时的优先级顺序是：内存 > IndexedDB > 服务端冷存储。

页面打开后，前端先读 IndexedDB（浏览器本地存储），立刻把旧内容渲染到对话区域，同时发恢复请求给服务端。

用户看到的效果是：内容已经渲染了，光标在文本末尾一直不停地闪烁，新的文字继续流出。用户根本不知道这是一次恢复，会认为只是'暂停了一下'。这样设计对用户体验来说比较友好～"

更健壮的代码实现如下，大家可以参考一下：

# 伪代码示意
class StreamingCheckpointManager:
    def __init__(self):
        self.redis = RedisClient()
        self.db = Database()

    async def freeze_generation(self, checkpoint_id: str, context: GenerationContext):
        # 1. 序列化生成状态（包含KV Cache和token序列）
        serialized = self.serialize_context(context)

        # 2. 写入Redis热存储（1小时TTL）
        await self.redis.setex(
            f"generation:{checkpoint_id}", 
            ttl=3600, 
            value=serialized
        )

        # 3. 异步写入数据库冷存储（7天TTL）
        asyncio.create_task(
            self.db.archive_generation(checkpoint_id, serialized, retain_days=7)
        )

    async def resume_generation(self, checkpoint_id: str, client_offset: int):
        # 1. 先查Redis
        state = await self.redis.get(f"generation:{checkpoint_id}")

        # 2. Redis未命中，查数据库
        if not state:
            state = await self.db.get_generation(checkpoint_id)
            if not state:
                raise CheckpointNotFound("生成记录已过期或不存在")

        # 3. 反序列化上下文
        context = self.deserialize_context(state)

        # 4. 如果客户端offset小于服务端已生成量，先补发历史内容
        if client_offset < context.output_length:
            await self.replay_history(client_offset)

        # 5. 如果生成尚未完成，继续流式输出
        if context.state != GenerationState.COMPLETED:
            await self.continue_generation(context)

面试官："如果用户换了设备呢？比如手机断了，在电脑上打开同一个页面，如何解决同步？"

答："这是更业务场景的功能实现了。我们可以把 checkpoint 与用户账号绑定，而不是设备绑定。电脑端进入同一会话时，检测到该会如果话存在 PAUSED 状态的 checkpoint，就会提示用户：'检测到您在手机端有未完成的生成，是否继续？' 这对跨设备协作的场景非常有用。"

第五问：极限边界场景探索（考验求职者的创新和思考能力了）

面试官："我问几个边界情况。第一，AI生成恢复时，已生成的内容过长，重新组装 Prompt 再发给模型，上下文窗口溢出了怎么办？"

答："可以对已生成内容，做智能摘要压缩，只保留关键结论作为上下文，而不是全文重传。我们可以在 Prompt 里区分 history_summary 和 continuing_context，让模型知道'这是前文摘要，请基于它继续完成'。"

这是一个非常实用且高频的解决方案，建议大家在AI项目中都采用。

面试官："第二个问题，LLM 有随机性，恢复后续写时，风格变了、人称变了，前后不一致怎么办？"

答："在恢复 Prompt 里注入风格锚点（style anchor），明确告知模型'请保持前文的第一人称叙述风格'。同时，checkpoint 里记录了生成时的 temperature 和 top_p，恢复时严格复用，最大程度保证一致性。"

面试官："第三个问题，如果模型版本升级了，旧版 KV Cache 新版加载不了，如何解决呢？"

答："可以通过序列化时加入模型版本标识和序列化协议版本。恢复时严格校验兼容性，不兼容时自动降级为'文本级恢复'——从文本断点重新生成，而不是推理状态断点。虽然会多花一点算力，但至少不会崩溃。"

此时面试官是不是已经急切的想要“招”你了。下面为了挽回自己的颜面，补充一个“加时赛”。

最后一问：如果让你给团队落地，优先级该怎么设计？

面试官："假设你们团队现在资源有限。让你排优先级，你会先做什么，后做什么？"

答："我会分三步来落地：

第一步：先做客户端 IndexedDB 缓存 + 服务端文本级断点续传。不碰 KV Cache 序列化，只记录已生成的文本和 offset。恢复时从文本断点重新调用模型生成。这样投入最小，但能解决80%的用户痛点。用时大概1-3天，当然也需要评估团队目前的技术实力，是否需要配合AI辅助来完成。

第二步：引入 Redis 热状态存储，实现KV Cache的序列化与恢复。这是性能拐点，能把恢复后的首 token 延迟从秒级降到毫秒级。如果用AI Coding，不考虑产品UI和交互逻辑，1天内应该可以搞定。

第三步：做网关层的心跳检测、多端同步、分级TTL策略。这是稳定性拐点，让方案能扛住生产环境的高峰流量。" 这个需要团队前后端运维多方配合，预计大概3-5天能完整落地。

面试官："为什么要先做客户端缓存，而不是先做服务端 KV Cache？"

答："因为我的思路中，用户体验的永远是第一优先级，比服务端性能优化更直观成本也更低。"

最后：给正在准备面试或转型AI的各位粉丝

如果大家正在准备AI工程、后端架构或大模型应用相关的面试，"流式生成状态恢复"是一个非常能体现工程深度的面试题。

给大家分享一个面试回答框架：**
**

场景痛点 → 架构分层 → 协议设计 → 边界兜底 → 落地优先级。

这个结构能帮大家把自己的技术回答变得既有广度又有深度。

从 15MB 减到 800KB，一行 ffmpeg 解决3D 渲染卡顿问题

ErpanOmer — Mon, 25 May 2026 03:52:02 GMT

在做跨境电商和独立站（如 Shopify）的前端架构时，商品详情页经常会遇到一个非常经典的业务需求：360度商品 3D 交互预览。

就是那种允许用户在移动端通过手指滑动，左右旋转商品、放大缩小，多角度查看商品细节的交互组件👆。

上个月，我们组的产品经理一拍脑袋，也想给新版详情页上这个功能。他兴冲冲地跑来找我：咱们直接用 Three.js，让 3D 美术给个 glTF 格式的 3D 模型文件，咱们在网页里用 WebGL 渲染，多高级！😁

我看着他，默默泼了一盆冷水：美术导出的高精度 glTF 模型起码 150MB 往上。加载这么大文件，海外用户的首屏白屏时间你来负责？用户稍微划得快一点，低端安卓机直接发热卡死甚至浏览器崩溃，你来写排障报告？

最终，我毙掉了他的 WebGL 方案，转而采用了一套极其克制、性能极佳的 视频帧平滑控制（Video Scrubbing） 方案。

今天，我不聊虚的技术趋势，就拿这个真实的开发实战，聊聊前端在处理 3D 视觉交互时的技术选型博弈，以及如何用一行极度硬核的 ffmpeg 优化命令，彻底榨干移动端 3D 交互的性能🤔。

网页端 3D 交互的三种技术路线

在网页端实现 360 度商品预览，行业里目前主要有三条路线，每一条我都踩过深坑：

路线 1：多帧图片序列拼接（Sprite 拼图）

通过在影棚里用 36 个或 72 个角度拍摄商品照片，最后在前端通过鼠标/触摸事件，动态切换 img 的 src 或者是控制一张超大雪碧图（Sprite）的 background-position。

加载极其恶心。72 张高分辨率图片合起来起码有 20MB。如果你不预加载，用户划动时会严重闪烁白屏；如果你预加载，用户的网络带宽会被瞬间吃满，首屏直接卡死。这个方案直接 Pass👋

路线 2：`Three.js / WebGL` 原生模型渲染

直接把 3D 模型文件（glTF、USDZ）加载到页面中，用 WebGL 渲染器进行实时光照和渲染。

这个方案是可行，也是比较主流，但性能开销是灾难级的。移动端 GPU 加速会导致手机迅速发烫。更致命的是，为了能在网页端流畅运行，美术必须对模型进行极度残忍的减面和贴图压缩，导致渲染出来的材质有一股极其廉价的塑料感，完全失去了高端商品的质感🤷‍♂️。

路线 3：3D 离线渲染视频 + 视频帧控制（`Video Scrubbing`）

让 3D 美术直接在 Blender 或 C4D 里，用最顶级的离线光线追踪（Ray Tracing）渲染器，渲染一段商品匀速自转一圈的高保真视频（比如 2 秒，60帧）。在前端，我们直接使用 video 标签嵌入这段视频，禁用自动播放。当用户在屏幕上左右滑动时，我们不播放视频，而是计算滑动的位移量，直接修改 video.currentTime，实现手动拨动商品旋转的效果。

<div class="video-3d video-3d--inline js-video-3d " data-video-3d-mode="inline"
  data-video-src="https://cdn.shopify.com/videos/c/o/v/b34e306cdf7d460881139e3b2820d092.mp4"
  data-desktop-video-src="https://cdn.shopify.com/videos/c/o/v/b34e306cdf7d460881139e3b2820d092.mp4"
  data-mobile-video-src="https://cdn.shopify.com/videos/c/o/v/3e7ca0f840074648943a3ce065ed9f00.mp4" data-poster-src=""
  data-preload="metadata" data-lazy-load="true" data-rotate-sensitivity="1" data-duration-fallback="3"
  data-mobile-seek-fps="30" data-enable-zoom="false" data-min-zoom="1" data-max-zoom="2" data-wheel-step="0.08"
  data-trigger-selector="" style="
    --video-3d-bg: #f7f7f7;
    --video-3d-aspect-ratio: 1280 / 880;
    --video-3d-object-fit: contain;
    --video-3d-dialog-width: 1600px;
  " aria-label="Interactive 360 degree product video">

  <div class="video-3d__viewer js-video-3d-viewer is-metadata-ready is-ready is-interacted is-motion-enabled">
    <div class="video-3d__stage js-video-3d-stage">
      <div class="video-3d__media js-video-3d-media" style="transform: translate3d(0px, 0px, 0px) scale(1);">
        <video class="video-3d__video js-video-3d-video" muted="" playsinline="" webkit-playsinline="" preload="auto"
          draggable="false" disablepictureinpicture="" controlslist="nodownload noplaybackrate noremoteplayback"
          aria-label="Interactive 360 degree product video"
          src="https://cdn.shopify.com/videos/c/o/v/b34e306cdf7d460881139e3b2820d092.mp4"></video>
      </div>
      <div class="video-3d__loader" aria-hidden="true">
        <span class="video-3d__spinner"></span>
      </div>
      <div class="video-3d__hint js-video-3d-hint" aria-hidden="true">
        Drag to rotate / 360 view
      </div>
      <button class="video-3d__reduced-button js-video-3d-reduced-button" type="button">
        Enable 360 view
      </button>
      <div class="video-3d__error" role="status">
        360 video is unavailable.
      </div>
    </div>
  </div>
</div>

渲染质量是电影级的，金属的光泽、皮革的纹理完美保留；视频文件的压缩率极高，一段 1080P 的自转视频可以被压缩到 1MB 左右，加载极快，且完全不消耗手机 GPU。

但这套方案有一个致命的问题：在移动端，当你用手指快速滑动屏幕时，视频画面会产生极其严重的卡顿、抖动和明显的延迟响应。

为什么在移动端，视频拖动会卡顿？

在解决这个问题前，我们必须先理解视频编码的底层机制。

视频之所以能被压缩得这么小，是因为它采用了 帧间压缩（Temporal Compression） 技术。

视频帧被分为三种类型：

I 帧（Intra-coded picture，关键帧）： 包含完整的单张静态图像，可以独立解码（相当于一张完整的 JPEG 格式图片）。
P 帧（Predicted picture，预测帧）： 只记录与前一个帧的差异数据。解码它，必须先解码它前面的帧。
B 帧（Bi-directional predicted picture，双向预测帧）： 记录与前后帧的差异。解码它，需要同时参考前一帧和后一帧。

为了最大化压缩体积，常规视频的 I 帧间隔（也就是常说的 GOP 尺寸）非常大，通常是 250 帧以上。这意味着每隔 250 帧才有一个完整的关键帧。

当你用手指快速拖拽商品时，浏览器需要将 video.currentTime 频繁设置到任意时间点（比如从第 10 帧跳转到第 45 帧）。

这时，浏览器的视频解码器会瞬间崩溃。因为它为了渲染出第 45 帧（P/B帧），必须强行回溯到第 1 帧（最近的 I 帧），然后一口气在内存中把中间的 44 帧全部计算一遍。

如果用户在屏幕上快速来回摩擦，解码器的计算量会呈指数级飙升，导致严重的掉帧、卡死和发热。

用ffmpeg 降维打击：一行命令解决移动端 3D 抖动

既然找到了病因，解法就非常明确了：我们需要通过特定的编码参数，彻底摧毁视频的帧间依赖，让浏览器能够以极低的 CPU 开销，进行任意帧的瞬间定位（Scrubbing）。

经过对 iOS Safari 和各大安卓浏览器内核的反复压测，我最终整理出了下面这行专为移动端交互而生的 ffmpeg 优化命令：

ffmpeg -i input.mp4 -an -vf "scale=1280:880,fps=30,format=yuv420p" \
-c:v libx264 -profile:v main -level:v 4.0 -preset slow -crf 22 \
-g 6 -keyint_min 6 -sc_threshold 0 -bf 0 -movflags +faststart \
product-360-mobile-gop6.mp4

这行命令看起来普通，但每一个参数都是为了榨干移动端 H.264 解码性能而精确调优的：

-an：彻底剥离音频。商品交互图不需要声音，删掉音频不仅能省带宽，还能防止浏览器因为自动播放/媒体策略而拦截视频。
-g 6 -keyint_min 6：强行将最大和最小 GOP 长度锁死在 6 帧。在 30fps 的视频里，这意味着每隔 0.2 秒就有一个绝对完整的 I 帧。浏览器在任意定位时，最多只需要解码 5 个中间帧，瞬间降低解码器的内存计算负载。
-sc_threshold 0：禁用场景切换检测。防止 ffmpeg 在画面变动大时擅自插入额外的非等距 I 帧，确保关键帧分布极其均匀，保证滑动时的手感绝对线性。
-bf 0： 【致命一击】 彻底禁用 B 帧（双向预测帧）。B 帧需要向前向后双向查找，在来回摩擦交互时，B 帧是造成卡顿的第一元凶。设置为 0 之后，视频只保留 I 帧和 P 帧，解码器只需单向线性解码，速度发生质的飞跃。
-movflags +faststart： 将视频的索引信息（moov atom）强行移动到文件的最头部。这样浏览器只要下载了视频开头的几个字节，就能立刻开始响应拖拽定位，无需等待整个视频加载完毕。

通过这行命令导出的 1280x880 视频，文件体积控制在 800KB 左右。

将手势映射到视频时间轴

底层地基用 ffmpeg 夯实之后，前端的代码实现变得极其清爽，甚至不需要引入任何第三方库。

我们只需要监听 touchstart 和 touchmove 事件，计算出滑动的距离比例，然后等比映射到视频的 duration 即可：

// 前端 3D 视频控制逻辑
const video = document.getElementById('product-360-video');
let startX = 0;
let startProgress = 0;

// 阻止默认的滚屏行为，专心处理左右摩擦
const handleTouchStart = (e) => {
  startX = e.touches[0].clientX;
  // 记录开始滑动时视频的当前进度比例
  startProgress = video.currentTime / video.duration;
};

const handleTouchMove = (e) => {
  if (!video.duration) return;
  
  const currentX = e.touches[0].clientX;
  const deltaX = currentX - startX;
  
  // 视口宽度对应的最大滑动距离，可以根据手感调整阻尼系数
  const swipeRange = window.innerWidth * 1.5; 
  const progressDelta = deltaX / swipeRange;
  
  // 计算最新的进度，并做好边界处理（首尾循环相连）
  let nextProgress = startProgress - progressDelta;
  if (nextProgress < 0) nextProgress += 1;
  if (nextProgress > 1) nextProgress -= 1;
  
  // 精确跳转到目标帧时间，由于 -bf 0 和低 GOP 限制，这次跳转将是 0 延迟的
  video.currentTime = nextProgress * video.duration;
};

video.addEventListener('touchstart', handleTouchStart, { passive: true });
video.addEventListener('touchmove', handleTouchMove, { passive: false });

感受

在前端圈，大家很容易陷入一种唯技术论的误区。觉得用上了最新的 WebGL、写了一大堆复杂的 Shader 材质、给页面塞了十几兆的 3D 模型，这才叫技术实力。

但对于要扛起商业转化率、注重用户体验的真实项目（尤其是跨境独立站）来说，在保证画质达到电影级的前提下，用最轻量的带宽、最低的硬件功耗，实现绝对丝滑的交互，才是真正的工程品味😁。

下一次面对类似的 360 度交互需求，别急着去写几百行复杂的 Three.js 逻辑了。

试着用 C4D 导出一款高保真视频，配合这行 ffmpeg 命令，你只需要用三十行干净的原生 JS 代码，就能在移动端上，给用户呈现出丝滑无比、极其惊艳的 3D 视觉体验。

如果喜欢点赞 + 收藏😁

尤雨溪亲自点赞！用 Vue 3 写原生 App，这个框架终于来了！

大前端历险记 — Mon, 25 May 2026 03:42:09 GMT

告别 WebView 的卡顿，像写 Vue 3 一样写真正的原生应用 这一次，你的 .vue 文件可以直接跑出 Swift/Kotlin 的性能！

大家好，我是大鱼。

在移动端开发的世界里，Vue 开发者似乎总是“低人一等”。

React 有 React Native，Google 有 Flutter，而 Vue 生态长期缺少一个能与之并肩的“真·原生”跨平台方案。

直到 NativeScript-Vue 3 的出现，并被 Vue 之父尤雨溪亲自点赞——这一切，终于迎来了改变。

🧐 它是什么？为什么尤大亲自站台？

NativeScript-Vue 3 是一个基于 Vue 3 核心的跨平台原生移动开发框架。

它的核心理念很简单：没有 WebView，没有 DOM——你写的 <template> 直接编译成 iOS 的 UIKit 和 Android 的 AppCompat 原生组件。

一句话总结：Vue 的自定义渲染器 + NativeScript 原生引擎

📱 小程序支持？先说清楚！

这是很多读者最关心的问题，我直接把结论放在前面：

❌ NativeScript-Vue 3 不支持微信小程序、支付宝小程序、抖音小程序等任何小程序平台。

它的定位非常纯粹：只做 iOS 和 Android 原生 App，一套代码，两端运行。

为什么不做小程序？

这是框架的设计哲学决定的：

技术特性	NativeScript-Vue	uni-app / Taro
渲染层	原生 UIKit/AppCompat	WebView / 小程序专用渲染
运行环境	V8 / JavaScriptCore	小程序运行时 / WebView
核心目标	原生级别性能	多端适配能力

NativeScript 的底层原理是直接调用 iOS/Android 的原生 API，而小程序的运行环境是完全不同的生态，两者不兼容。

那我想要小程序怎么办？

如果你需要覆盖 小程序 + App + H5，目前主流的选择仍然是 uni-app 或 Taro。

但如果你满足以下条件，NativeScript-Vue 3 会是更好的选择：

✅ 只做 iOS / Android，不需要小程序
✅ 追求接近原生的性能（重动画、重交互、长列表流畅）
✅ 团队熟悉 Vue 3 生态，不想学 Swift/Kotlin
✅ 需要直接调用硬件能力（蓝牙、NFC、传感器等）

一句话总结：想多端通吃选 uni-app，想做精品原生 App 选 NativeScript-Vue。

💔 为什么是时候说再见了？

很多朋友还在用 uni-app 或 Hybrid 方案，但其中的痛点只有开发者自己知道：

维度	传统混合开发	NativeScript-Vue 3
渲染机制	WebView 渲染，启动慢、长列表卡顿	原生渲染，直接调用系统 UI 组件
原生能力	需要各种桥接、renderjs，维护成本高	直接调用原生 API 和 SDK，零延迟
开发体验	厂商锁仓，Vite/Pinia 支持滞后	Vite + TS + Vue 3 全家桶，现代前端体验
包体积	自带 WebView 内核，体积臃肿	纯原生二进制包，平均小 30%

有了它，你不仅获得了 React Native 同级别的性能，还保留了 Vue 3 极致的开发体验。

✨ 三大核心特性：Vueer 的“王炸”

1. 纯粹的 Vue 3 开发体验

完全支持 <script setup>、Composition API、响应式系统。你甚至可以直接使用 Pinia 作为状态管理，零改动接入！

<script setup>
import { ref } from 'vue';

const count = ref(0);
const message = ref('Hello Native!');
</script>

<template>
  <Page>
    <ActionBar title="我的原生App" />
    <StackLayout class="p-4">
      <Label :text="message" class="text-2xl" />
      <Button @tap="count++" :text="`点击次数：${count}`" />
    </StackLayout>
  </Page>
</template>

2. 超强“外挂”：直接调用原生 API

这是它最硬核的地方。它没有桥接层，JS 和原生运行在同一线程，同步直接调用。

这意味着你可以直接在 Vue 组件里写 Android 的 Intent 跳转或 iOS 的 CBCentralManager：

// 直接在组件中调用原生设备信息
import { device } from '@nativescript/core';

console.log(`系统版本: ${device.osVersion}`);
console.log(`设备型号: ${device.model}`);

3. Vite 加持的极速热重载

终于，移动端开发也能享受 Web 端的毫秒级 HMR了！保存代码，模拟器直接更新，无需重新编译。

🛠️ 5 分钟极速上手

第一步：安装 NativeScript CLI

npm install -g @nativescript/cli

第二步：创建 Vue 3 项目

ns create my-vue-app --template @nativescript/vue-template

第三步：运行起来！

# 连接手机或打开模拟器
ns run android   # 或 ns run ios

你会发现，你的第一个纯原生 Vue App 就跑起来了！🚀

⚠️ 避坑指南（必看！）

虽然很香，但由于架构不同，Vue 生态的部分库是无法使用的：

插件	是否可用	说明
Pinia	✅	零改动，直接使用
vue-i18n	✅	实测正常
VueUse	⚠️	仅无 DOM 的 Utilities 可用
Vue Router	❌	官方推荐用 NativeScript 帧导航 `$navigateTo`
Vuetify / Element Plus	❌	依赖 CSS & DOM，无法渲染

💡 检测小技巧：安装包后，grep -r "document\|window" node_modules/xxx，没输出说明大概率安全！

🗣️ 真实体验：一个月的开发经历告诉你

有开发者用 NativeScript-Vue 3 花了一个月时间，做了一个完整的日程管理+AI助手 App（影时间），他的真实感受是：

好的地方：

用 Vue 写原生 UI，Composition API 0 学习成本

同步调用原生 API 很爽，没有延迟

包体积小，启动快

不太爽的地方：

社区真的小，问题搜不到，文档写得比较简略

调试有时候头疼，原生堆栈错误要自己定位

JS 在主线程运行，耗时计算会阻塞 UI（适合中小项目）

🎯 写在最后

Flutter 很强，RN 也很成熟，但如果你是一个 Vue 3 的忠实拥趸，NativeScript-Vue 3 是你涉足原生应用开发最优雅、最低成本的路径。

它让 Vue 语法第一次 完整、无损、高性能 地跑在 iOS & Android 上。

但请理性选择：

需要小程序？👉 选 uni-app 或者 taro
做精品原生 App？👉 NativeScript-Vue 值得一试

IntelliJ IDEA 从卡顿到起飞，只用改这些。。。

苏三说技术 — Sun, 24 May 2026 09:44:29 GMT

前言

今天不聊高并发、不聊架构设计，想和大家聊一个每位Java程序员每天都在用的工具——IntelliJ IDEA。

说实话，用了多年IDEA，我踩过不少坑。

今天我把最经典的10个坑整理出来，希望能帮大家少走一些弯路。

很多小伙伴在工作中肯定也遇到过类似的问题，比如“IDEA突然变卡了”、“代码明明没错就是编译不过”、“Debug的时候断点不生效”等等。

这篇文章没有高深的理论，全是实战经验，小白也能看懂。

希望对你会有所帮助。

更多项目实战在我的技术网站：susan.net.cn/project

IDEA的优缺点和使用场景

在正式开讲之前，我们先来客观地看一下IDEA这款IDE到底好在哪、不好在哪，以及适合什么场景。

IDEA的优点

智能代码提示：相比Eclipse，IDEA的代码分析引擎更强大，能根据上下文给出更精准的补全建议。
重构能力极强：重命名、提取方法、改变签名等重构操作非常安全，能自动修复所有引用。
内置工具丰富：版本控制、数据库客户端、HTTP Client、终端等一应俱全，不用来回切换。
插件生态完善：Lombok、MyBatis、SonarLint等插件几乎覆盖了所有开发场景。
调试功能强大：条件断点、表达式求值、远程调试、内存分析等，排查问题非常高效。

IDEA的缺点

内存占用较高：默认配置下轻松吃掉2-4G内存，老机器跑起来比较吃力。
索引机制耗时：每次导入项目或依赖变更，都会触发重新索引，大项目可能要等几分钟。
配置相对复杂：很多优化需要手动调整，新手容易被各种设置搞晕。
商业软件：Ultimate版本收费，虽然可以用Community版，但很多企业级功能（如Spring、JPA、JS等）需要付费。

适用场景

场景	是否推荐	说明
大型Java/Spring项目	⭐⭐⭐⭐⭐	IDEA的Spring支持无出其右
中小型Web项目	⭐⭐⭐⭐⭐	开发效率远高于Eclipse
多语言混合项目（Java+JS+Python）	⭐⭐⭐⭐⭐	Ultimate版支持所有主流语言
老旧机器（内存<8G）	⭐⭐	勉强能用，但建议升级配置或换VS Code
纯前端项目	⭐⭐	VS Code可能更合适
学生/开源学习	⭐⭐⭐⭐	Community版足够用

好了，了解这些背景之后，咱们正式进入主题——我踩过的10个坑。

第1个坑：越用越卡，CPU狂飙

现象

IDEA打开两三个小时之后，敲个代码都要卡两秒，鼠标转圈圈，CPU动不动就100%。

重启一下又好一会儿，过一会儿又卡了。

原因分析

IDEA的卡顿通常有两个原因：内存分配不足和索引被频繁触发。

先说说内存。

IDEA默认的堆内存只有512MB-1GB左右，对于现代项目（尤其是微服务项目，一个workspace里有十几个module）来说，这点内存根本不够用。

JVM频繁进行Full GC，自然就卡了。

再说说索引。

IDEA会对项目中的所有文件建立索引，以便实现快速搜索、跳转等功能。

但是如果你开启了“自动索引外部文件”或者项目中有一个巨大的node_modules文件夹（前端同学懂得），IDEA就会一直尝试索引这些根本不需要索引的文件，CPU直接拉满。

解决方案

第一步，手动调整IDEA的内存配置。

找到IDEA安装目录下的idea64.exe.vmoptions文件（Mac在/Applications/IntelliJ IDEA.app/Contents/bin/idea.vmoptions），修改以下参数：

# 建议配置（8G内存机器）
-Xms2048m           # 初始堆内存，建议直接给到2G
-Xmx4096m           # 最大堆内存，给到4G
-XX:ReservedCodeCacheSize=512m   # 代码缓存
-XX:+UseG1GC        # 使用G1垃圾回收器，减少停顿
-XX:+UseStringDeduplication  # 去重字符串，节省内存

第二步，排除不需要索引的目录。

打开 File -> Settings -> Project Structure -> Modules，把那些不需要索引的文件夹（如node_modules、.git、target、build等）标记为Excluded。

做完这两步，IDEA的流畅度会有一个质的飞跃。

第2个坑：getter/setter报红

现象

本来好好的项目，更新了IDEA或者改了某个配置之后，所有用@Data、@Getter注解的类的调用地方突然飘红，编译失败，提示“找不到getXxx方法”。

原因分析

Lombok的工作原理是在编译期通过注解处理器自动生成getter/setter等代码。

IDEA需要安装Lombok插件才能识别这些生成的代码，否则就会报红。

这个坑通常发生在以下几种情况：

升级IDEA后，旧版Lombok插件不兼容
项目的Lombok依赖版本和插件版本不一致
开启了IDEA的“注解处理”但没有正确配置

解决方案

第一步，检查Lombok插件是否安装并启用。File -> Settings -> Plugins 搜索Lombok，确保已安装且勾选。

第二步，打开File -> Settings -> Build, Execution, Deployment -> Compiler -> Annotation Processors，勾选“Enable annotation processing”。

第三步，确保项目的pom.xml或build.gradle中引入了Lombok依赖，并且版本不要太老。推荐版本：

<!-- Maven -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.30</version>
    <scope>provided</scope>
</dependency>

第四步，如果上面三步都做了还是不行，尝试 File -> Invalidate Caches and Restart，清空IDEA的缓存并重启。这个操作能解决IDEA里80%的玄学问题。

有一次我遇到一个特别诡异的情况：同一个项目，同事的IDEA没问题，我的就是报红。

最后发现是.idea目录下的配置文件冲突了，删掉.idea目录让IDEA重新生成就正常了。

第3个坑：Debug断点死活进不去

现象

调试的时候，我在一个Service方法的第一行打了个断点，但是跑起来断点根本不生效，代码直接执行过去了。

更离谱的是，有时候断点上的对勾是灰色的。

原因分析

这个坑有几种可能：

断点打在不可执行的代码行上：比如接口的方法、空行、注释行。IDEA的断点只能打在可执行的字节码行上。
开启了“静默断点”或“禁用所有断点”：断点图标上有一个斜线，表示暂时禁用。
代码被JIT内联优化了：在release模式下，热点方法可能被内联，导致断点位置和源码对应不上。
多线程环境下，断点被其他线程绕过了：如果你打了条件断点且条件一直为false，自然不会进去。

解决方案

首先，检查断点图标。正常断点是红色圆点，如果带斜线，点击右键取消“Disable”。

或者按 Ctrl + Shift + F8 打开断点管理面板，看看是不是所有断点都被禁用了。

其次，确保断点打在可执行行上。比如：

// ❌ 以下位置不能打断点
public void doSomething() // 方法签名行

// ✅ 这样是可以的
public void doSomething() {
    System.out.println("这里可以打断点");  // 第一行大括号后的有效代码
}

第三，如果是在多线程调试中，检查一下条件断点。IDEA支持在断点上右键设置条件，比如 str == null。如果条件永远不满足，断点当然不会触发。

第四，终极方案：使用 Thread.currentThread().getStackTrace() 打印堆栈来定位问题，或者改用日志输出。

第4个坑：控制台中文乱码

现象

运行项目，控制台打印的日志中，中文全部变成了 ??? 或者 \uXXXX 这样的乱码。

System.out.println("你好") 输出的是“???”。

原因分析

乱码的本质是编码不一致。

IDEA的控制台、项目的源文件编码、JVM的默认编码、操作系统编码这四个地方只要有一个对不上，就可能出现乱码。

常见的情况是：

源文件是UTF-8编码，但IDEA控制台用的是GBK
或者反过来，源文件是GBK，控制台用UTF-8
JVM的file.encoding参数没有正确设置

解决方案

第一步，统一所有地方的编码为UTF-8。

打开 File -> Settings -> Editor -> File Encodings：

Global Encoding: UTF-8
Project Encoding: UTF-8
Default encoding for properties files: UTF-8
勾选“Transparent native-to-ascii conversion”

第二步，修改IDEA控制台的编码。在 Help -> Edit Custom VM Options 中添加：

-Dfile.encoding=UTF-8
-Dconsole.encoding=UTF-8

第三步，对于Maven项目，在pom.xml的maven-surefire-plugin和maven-compiler-plugin中也指定编码：

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
</properties>

第四步，如果用的是Logback或Log4j，检查日志配置文件的编码，比如Logback：

<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
        <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        <charset>UTF-8</charset>  <!-- 关键 -->
    </encoder>
</appender>

做完这些配置之后，重启IDEA，乱码问题一般就能解决了。

第5个坑：Git提交时多了.idea文件

现象

用IDEA自带的Git提交代码时，Commit Changes 窗口里总是出现一些不应该提交的文件，比如.idea/workspace.xml、target/目录下的class文件、.iml文件等。

有时候一不小心就提交上去了，污染了Git仓库。

原因分析

IDEA默认会把项目的.idea目录和.iml文件纳入版本控制，因为这些文件记录了项目的配置信息。

但问题是，这些文件里可能包含本地路径、个人配置等环境相关的信息，不同机器之间不应该共享。

target/目录是编译产物，更不应该提交。

根本原因是没有配置.gitignore文件，或者配置了但IDEA没有正确识别。

解决方案

在项目的根目录下创建.gitignore文件，把以下内容放进去：

# Compiled class file
*.class
target/
out/

# IntelliJ IDEA
.idea/
*.iml
*.iws
*.ipr
.idea/workspace.xml
.idea/tasks.xml
.idea/gradle.xml
.idea/compiler.xml
.idea/libraries/

# Log file
*.log
*.log.gz

# OS generated files
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db

然后在IDEA中，打开 Settings -> Version Control -> Ignored Files，确保没有任何冲突的规则。

如果你的.gitignore文件已经在Git仓库中，并且之前已经错误地提交了.idea目录，需要先执行命令从Git缓存中移除：

git rm -r --cached .idea
git commit -m "Remove .idea from git"

之后再提交，就只会看到需要提交的源码文件了。

第6个坑：Maven依赖下载巨慢

现象

在IDEA中刷新Maven项目（Reload All Maven Projects）时，右下角一直在转圈，下载依赖特别慢，有时候直接超时报“Transfer failed”或者“Read timed out”。

原因分析

Maven默认的中央仓库在国外，网络延迟大，下载速度自然慢。

IDEA虽然内置了Maven，但默认会使用Maven自带的settings.xml，其中没有配置国内镜像。

另外，IDEA的Maven和命令行Maven可能会共用同一个本地仓库（~/.m2/repository），如果同时操作，会出现锁文件冲突。

解决方案

第一步，配置国内镜像源。

在 File -> Settings -> Build, Execution, Deployment -> Build Tools -> Maven 中，找到 User settings file，点击“Override”，然后选择或创建一个settings.xml文件，填入以下内容：

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 
          http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <mirrors>
        <!-- 阿里云Maven镜像 -->
        <mirror>
            <id>aliyunmaven</id>
            <mirrorOf>central</mirrorOf>
            <name>阿里云公共仓库</name>
            <url>https://maven.aliyun.com/repository/public</url>
        </mirror>
    </mirrors>
    
    <profiles>
        <profile>
            <id>jdk-1.8</id>
            <activation>
                <activeByDefault>true</activeByDefault>
                <jdk>1.8</jdk>
            </activation>
            <properties>
                <maven.compiler.source>1.8</maven.compiler.source>
                <maven.compiler.target>1.8</maven.compiler.target>
                <maven.compiler.compilerVersion>1.8</maven.compiler.compilerVersion>
            </properties>
        </profile>
    </profiles>
</settings>

第二步，在Maven设置中，把“Work offline”关掉（除非你真的要离线工作），把“Import Maven projects automatically”打开，这样依赖变更时会自动下载。

第三步，如果你的网络环境特别差，可以尝试配置IDEA的HTTP代理。Settings -> Appearance & Behavior -> System Settings -> HTTP Proxy，如果公司有内网代理，填进去即可。

配置完成后，点击Maven面板上的“Reload All Projects”按钮，下载速度应该明显提升。

第7个坑：代码编译通过，运行却报错

现象

在IDEA里Maven编译没有任何错误，mvn clean compile也成功了。

但是运行main方法或者启动Spring Boot时，控制台报错：java.lang.ClassNotFoundException: com.xxx.SomeClass。

原因分析

这个坑的原因很隐蔽：IDEA的编译器和Maven的编译输出目录不一致。

IDEA默认的编译输出目录是 项目根目录/out/ 或者 target/classes/，而Maven的编译输出目录是 target/classes/。

如果你修改过项目结构，或者IDEA的缓存乱了，可能会导致IDEA运行时用的classpath里找不到某些类。

另一个常见原因是：使用了Lombok，但是IDEA的注解处理器没有生成代码，或者生成的代码路径不对。

解决方案

首先，打开 File -> Settings -> Build, Execution, Deployment -> Compiler，确保“Build project automatically”是勾选的（但注意这会在你保存文件时自动编译，对性能有影响）。

然后，检查 File -> Project Structure -> Modules，看每个module的“Output path”和“Test output path”是否指向了正确的目录。一般来说，Maven项目应该指向target/classes和target/test-classes。

最暴力的解决方法：点击 Build -> Rebuild Project 清空所有编译输出，然后重新编译。如果还不行，执行 File -> Invalidate Caches and Restart 清空缓存。

还有一个绝招：用Maven命令行先打包，然后手动运行打好的jar包，看是不是同样的问题。

如果jar包能运行，那就是IDEA的运行配置有问题；如果jar包也报错，那就是代码本身有依赖问题。

第8个坑：快捷键失灵

现象

习惯了用 Ctrl+C、Ctrl+V 复制粘贴代码，突然有一天发现快捷键不管用了，或者按下去之后出现奇怪的行为（比如弹出某个面板、删除文字等）。

更离谱的是，Ctrl+Alt+L 格式化代码也无效。

原因分析

IDEA的快捷键冲突通常有两种情况：

与其他软件的快捷键冲突：比如微信PC版的截图快捷键是Ctrl+Alt+A，和IDEA的一些插件快捷键重复；搜狗输入法的Ctrl+Shift+F会切换简繁体。
IDEA的keymap被无意中修改了：可能是不小心按到了“切换keymap”的快捷键，或者某个插件改动了设置。

解决方案

第一步，检查是否切换了keymap。

打开 File -> Settings -> Keymap，看看当前选中的keymap是不是你常用的（比如Windows默认是Default，Mac是Mac OS X）。如果显示Default copy或者别的，说明被改过了。可以点击“Restore Defaults”恢复默认。

第二步，排查外部软件冲突。

常见的冲突有：

微信：Ctrl+Alt+W
搜狗/微软拼音：Ctrl+Shift+F（简繁体切换）、Ctrl+Shift+E（表情）
QQ：Ctrl+Alt+A（截图）
网易云音乐：Ctrl+Alt+上/下（音量）

解决方法是去这些软件里修改快捷键，或者直接关闭它们。我个人的习惯是写代码的时候把聊天软件退了，清净。

第三步，如果只有某个特定快捷键失效，可以在Keymap里搜索这个快捷键的动作，看看是不是被占用了。

比如搜索Reformat Code（格式化代码），默认是Ctrl+Alt+L，如果显示多个动作，说明有冲突，可以右键移除一个。

第9个坑：连不上MySQL

现象

IDEA自带的Database工具（很好用，很多小伙伴可能不知道）连接MySQL时，报错：The server time zone value '???ú±ê×??±??' is unrecognized 或者 Could not create connection to database server.

原因分析

MySQL 8.0以上版本要求明确指定时区参数serverTimezone。IDEA的Database连接配置默认不包含这个参数，导致了错误。

解决方案

在IDEA的Database面板中，点击数据源设置，进入“Advanced”选项卡，手动添加一个参数：

Name: serverTimezone
Value: Asia/Shanghai 或者 UTC

如果还不行，在“General”页面的URL后面直接加上：

jdbc:mysql://localhost:3306/test?useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=utf-8

另外，如果是用Spring Boot项目的数据源配置，也建议在连接池的URL中加入这些参数，防止运行时报同样的错。

最后，检查一下MySQL驱动版本。IDEA默认会下载最新的驱动，但如果你的MySQL是5.7版本，用8.x的驱动可能会不兼容。

可以在数据源的“Driver”下拉菜单中选择旧版本。

第10个坑：提交代码时自动格式化

现象

团队协作时，你提交代码前IDEA自动帮你格式化了代码（Ctrl+Alt+L）。

结果提交上去之后，整个文件的缩进、换行、空行全变了。

你的改动可能只有一行，但是git diff里却显示了整个文件几百行的变更。

代码Review的时候，同事根本看不出你到底改了啥。

原因分析

这是IDEA的“崇高”功能——在提交代码时自动执行代码格式化、优化导入等操作。

初衷是好的，希望保持代码风格统一。

但是，如果团队成员没有使用统一的代码格式化规则（比如每个人的缩进设置不同：有的用4空格、有的用2空格、有的用Tab），就会导致互相覆盖、diff爆炸。

解决方案

有两种解决思路：

方案一：统一团队代码格式（推荐）

在项目根目录下放置一个.editorconfig文件，这是各大IDE和编辑器共同遵守的格式规范：

# .editorconfig
root = true

[*]
charset = utf-8
indent_style = space
indent_size = 4
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.java]
indent_size = 4

[*.xml]
indent_size = 2

IDEA会自动识别.editorconfig，并提示是否采用。这样所有人都用同一套规则。

同时，在IDEA中导出代码格式化规则（File -> Settings -> Editor -> Code Style -> Java -> Manage -> Export），把文件放进项目版本控制，让同事导入。

方案二：关闭自动格式化功能

如果你不想自动格式化，可以关掉。打开 File -> Settings -> Version Control -> Commit，把“Reformat code”、“Optimize imports”、“Rearrange code”前面的勾全部取消。

这样一来，提交的时候就只会提交你手动改动的部分，不会动其他代码。当然，你需要自己保证代码格式是OK的。

个人建议采用方案一，这样既保持了代码整洁，又不会引起格式冲突。

总结

好了，10个坑终于讲完了。

我来帮大家快速回顾一下：

序号	坑	一句话解决方案
1	IDEA越来越卡	调大内存 + 排除无需索引的目录
2	Lombok失效	装插件 + 开启注解处理
3	断点进不去	打在有效行 + 检查禁用状态
4	控制台中文乱码	统一UTF-8 + JVM参数
5	Git提交了不该提交的文件	配置.gitignore + 移除已提交的
6	Maven依赖下载慢	配置阿里云镜像
7	ClassNotFoundException	检查编译输出目录 + Rebuild
8	快捷键失灵	检查keymap + 关闭冲突软件
9	数据库时区错误	添加serverTimezone参数
10	提交时自动改格式	统一.editorconfig或关闭自动格式化

最后用一张图来总结一下这些坑的应对思路：

写这篇文章，一方面是帮大家避坑，另一方面也是对自己这些年IDEA使用经验的一个总结。

工欲善其事，必先利其器。

IDEA确实是一个非常强大的工具，但再强大的工具，如果不会用、用不对，也会变成绊脚石。

希望这篇文章能给大家带来实实在在的帮助。

如果你也踩过其他“奇葩”的坑，欢迎在评论区留言分享。

咱们互相学习、共同进步！

更多项目实战在我的技术网站：susan.net.cn/project

SenseNova-U1 实战体验：从网页版生成，到 Mac 踩坑，再到 CUDA 服务器跑通本地部署

倔强的石头_ — Sat, 23 May 2026 01:38:26 GMT

最近试了一轮商汤开源的 SenseNova-U1。我一开始不是奔着“跑分”去的，而是想确认一件更实际的事：它到底能不能从在线体验过渡到本地部署，尤其是像我这种日常主力是 Mac 的开发环境，最后能不能把流程真实跑通。

这篇文章按我的实际操作顺序写：先看网页版效果，再记录 Mac 本地尝试，最后切到 CUDA 服务器完成部署和生成测试。中间有成功，也有失败。我尽量把命令、报错和判断都放出来，因为这些比只贴一张最终效果图更有参考价值。

先理解 SenseNova-U1：它不是单纯的文生图模型

官方介绍里，SenseNova-U1 的关键词是 NEO-Unify，定位是“原生统一多模态理解与生成”。这点和传统多模态方案不太一样：很多模型是一个视觉编码器接一个语言模型，生成任务再接另一个图像生成模块；而 SenseNova-U1 强调把理解、生成、图像编辑、图文交错等能力放进统一架构里。

从架构图看，它同时覆盖左侧的理解类任务和右侧的生成类任务。理解侧包括文本理解、视觉语言理解、知识推理、Agent 决策、空间智能；生成侧包括图像生成、图像编辑、信息图生成、交错图文生成、统一推理。

这个定位也决定了我后面的测试方向：不只看它能不能出图，还要看它在部署链路里是否能稳定加载、是否吃显存、是否对分辨率有约束。

官方还放了不少 benchmark 对比，能看到 SenseNova-U1-A3B-MoT 和 SenseNova-U1-8B-MoT 在多个理解、编辑、生成任务上和其他模型对比。

我这次实际部署用的是 sensenova/SenseNova-U1-8B-MoT。原因很简单：A3B-MoT 更大，本地和普通云 GPU 都更容易遇到资源问题；8B-MoT 更适合做个人实测。

官方资料：

GitHub: https://github.com/OpenSenseNova/SenseNova-U1
Hugging Face: https://huggingface.co/sensenova/SenseNova-U1-8B-MoT
SenseNova Skills: https://github.com/OpenSenseNova/SenseNova-Skills

网页版体验：先看模型能做什么

在本地部署前，我先用了网页版体验。这个阶段的目的不是研究环境，而是判断模型能力是否值得继续折腾本地部署。

第一个测试是信息图生成。我给的方向是“人生四个十年的 2x2 网格”，要求用物件、材质和年代数字表达不同人生阶段。返回结果是一个四象限信息图：10 岁、20 岁、30 岁、40 岁分别用玩具、耳机、书本、工具、药瓶、植物等物件表达阶段感。

这张图最让我意外的是，它不是简单把文字贴到画面上，而是尝试用“物化”的方式表达年龄。10 岁是积木和拼图质感，20 岁有耳机和金属数字，30 岁是书本和钟表，40 岁是工具、药瓶和植物。它生成的效果还是很符合我们的prompt的

第二个测试是 2D 卡通贴纸。我要求从同一男性角色出发，生成六张贴纸，并保留人物标志性特征，比如眼镜、笑容、发型，同时让每张贴纸有不同表情和文字。

这张更偏社交媒体素材。它保留了统一角色，六张贴纸分别表达“教师模式开启”“我需要咖啡……”“订阅！”“自拍时间到！”“让我来评分。”“太容易了”。从结果看，网页版已经能支撑不少轻量内容创作场景，尤其适合先做创意验证。

也正是因为网页版效果还可以，我才继续往本地部署走。

Mac 本地部署：可以搭环境，但不适合硬跑完整推理

我的主力机器是 MacBook Pro，配置是 Apple M1 Pro，8 核 CPU（6 个性能核心 + 2 个能效核心），16GB 内存，系统是 macOS 15.4.1，arm64 架构。第一反应当然是先在本机跑一遍。但虽然SenseNova-U1 官方环境默认是 Linux + CUDA，但还是想试一下。

官方项目的 pyproject.toml 要求 Python 版本是：

requires-python = ">=3.11,<3.12"

我一开始用 Python 3.12，直接被拒绝：

这一步说明了一个细节：不要看到本机 Python 新就直接用。SenseNova-U1 当前明确要求 Python 3.11，3.12 不行。

Mac 上正确的环境方向是：

brew install python@3.11
/opt/homebrew/opt/python@3.11/bin/python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip wheel setuptools

然后安装 macOS 版 PyTorch，而不是 CUDA 版 PyTorch：

pip install torch torchvision

项目依赖我没有直接 uv sync，因为官方 uv 配置会拉取 CUDA 12.8 的 PyTorch wheel，Mac arm64 不能安装这个包。我的方式是手动安装核心依赖：

pip install transformers==4.57.1 tokenizers==0.22.1 accelerate==1.10.1 \
  huggingface-hub==0.36.2 safetensors==0.6.2 sentencepiece==0.2.1 \
  "numpy>=1.24,<3" pillow==12.0.0 tqdm==4.67.1 packaging==25.0 httpx

pip install -e . --no-deps

pip install -e . --no-deps 的作用是把当前项目注册到 Python 环境里，否则运行示例脚本会出现：

ModuleNotFoundError: No module named 'sensenova_u1'

到这里，Mac 上的项目环境是能起来的。模型也能开始下载和加载。

但真正进入 MPS 推理时，问题来了。即使我只跑 512x512、4 steps 的最小文生图测试，模型加载到 MPS 时仍然触发了内存不足：

报错里最关键的是：

RuntimeError: MPS backend out of memory
MPS allocated: 18.04 GiB
max allowed: 18.13 GiB
Tried to allocate 96.00 MiB

这说明它还没真正开始生成图，就已经把 MPS 可用内存顶满了。

我又尝试了官方低显存模式：

python examples/t2i/inference.py \
  --model_path sensenova/SenseNova-U1-8B-MoT \
  --prompt "一张极简中文卡片，标题是 SenseNova-U1 Mac 本地部署测试，白底，科技感。" \
  --width 512 \
  --height 512 \
  --num_steps 4 \
  --cfg_scale 1.0 \
  --device mps \
  --dtype float16 \
  --attn_backend sdpa \
  --vram_mode low \
  --output outputs/mac_mps_low_test.png

结果不是 OOM，而是另一个更明确的问题：

核心报错是：

NotImplementedError: Inference requires a CUDA or XPU device (got device(type='mps')).
CPU / MPS lack the pinned-memory and stream primitives used here.

这个结论很清楚：Mac 可以完成环境适配和模型下载验证，但当前不适合作为 SenseNova-U1-8B-MoT 的完整本地推理主力环境。--vram_mode low 这类 offload 机制依赖 CUDA/XPU 的 pinned memory 和 stream，MPS 不支持。

这一段我反而觉得值得写进文章。因为很多时候“本地部署失败”不是无意义失败，它能帮助判断什么环境才是合理投入。

切到 CUDA 服务器：部署路线变得顺畅

Mac 这条路走不通后，我换到了云端 GPU Notebook。最终我拿到的环境是 NVIDIA GPU，实际验证里 PyTorch 能识别到：

torch: 2.8.0+cu128
cuda: 12.8
cuda available: True
gpu: NVIDIA GeForce RTX 3090

服务器环境截图如下：

CUDA 和 PyTorch 验证是本地部署里很重要的一步，建议不要跳过。我用的是：

python -c "import torch; print(torch.__version__); print(torch.version.cuda); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))"

输出确认 CUDA 可用：

安装好 PyTorch 后，我再安装 SenseNova-U1 的核心依赖：

pip install transformers==4.57.1 tokenizers==0.22.1 accelerate==1.10.1 \
  huggingface-hub==0.36.2 safetensors==0.6.2 sentencepiece==0.2.1 \
  "numpy>=1.24,<3" pillow==12.0.0 tqdm==4.67.1 packaging==25.0 httpx

pip install -e . --no-deps

这里我还是没有直接让依赖工具自动处理 PyTorch。原因是前面已经验证了 torch==2.8.0+cu128 和 GPU 可用，后续安装项目依赖时不希望 pip 或 uv 把 torch 版本改掉。

接着克隆项目：

cd /root/autodl-tmp
git clone https://github.com/OpenSenseNova/SenseNova-U1.git
cd SenseNova-U1

Hugging Face 下载问题：切镜像源并保存到数据盘

服务器默认访问 Hugging Face 不稳定，一开始直接加载：

--model_path sensenova/SenseNova-U1-8B-MoT

会报：

Network is unreachable
HTTPSConnectionPool(host='huggingface.co', port=443)

所以我改成先把模型下载到数据盘，再用本地路径加载。这里用国内镜像：

HF_ENDPOINT=https://hf-mirror.com huggingface-cli download sensenova/SenseNova-U1-8B-MoT \
  --local-dir /root/autodl-tmp/models/SenseNova-U1-8B-MoT \
  --resume-download \
  --max-workers 1

几个参数解释一下：

HF_ENDPOINT=https://hf-mirror.com：切到 Hugging Face 镜像源
--local-dir：把模型放到数据盘，避免占系统盘
--resume-download：支持断点续传
--max-workers 1：降低并发，提高弱网络下的稳定性

当然下面这种先export 然后验证也是可以的。

中途我确实遇到过 Broken pipe，重新执行同一条命令后会续传。最终下载完成时显示 214 个文件全部获取成功：

这很重要，因为它证明后续不是在线拉模型，而是从本地路径加载。

第一次生成：用 1024x1024 验证 CUDA 推理闭环

模型下载完成后，我没有继续走在线模型名，而是直接使用本地模型目录作为 --model_path。第一次成功生成用的是 1024x1024、30 steps、cfg_scale 4.0，这比单纯的连通性测试更接近实际可用效果。

cd /root/autodl-tmp/SenseNova-U1
mkdir -p outputs

python examples/t2i/inference.py \
  --model_path /root/autodl-tmp/models/SenseNova-U1-8B-MoT \
  --prompt "一张中文科技风信息图，标题为 SenseNova-U1 本地部署成功，画面包含 GPU 环境、模型下载、推理测试三个步骤，白色背景，蓝色科技感，清晰排版，中文文字清晰。" \
  --width 1024 \
  --height 1024 \
  --num_steps 30 \
  --cfg_scale 4.0 \
  --device cuda \
  --dtype bfloat16 \
  --attn_backend sdpa \
  --vram_mode balanced \
  --output outputs/sensenova_u1_cuda_quality_test.png

这张图里能看到三个关键信息：命令行已经从本地模型路径加载，checkpoint shards 正常加载完成，最终图片保存到了 outputs/sensenova_u1_cuda_quality_test.png。生成结果本身也符合提示词要求，包含“GPU 环境、模型下载、推理测试”三个步骤，说明 CUDA 服务器上的文生图链路已经跑通。

需要注意的是，脚本会提示 1024x1024 不在官方训练分辨率 bucket 中。这个警告不影响本次生成成功，也提醒我后面可以继续按官方 bucket 再跑一次更规范的 16:9 测试。

分辨率也有坑：不要随便填 1360x768

我随后尝试 16:9，但一开始用了 1360x768，结果脚本提示它不在官方训练 bucket 里，并在 patchify 阶段报 shape 错误。

官方支持的 bucket 里，16:9 对应的是：

2720x1536

所以后面我改成官方 bucket。这个细节很容易踩坑：SenseNova-U1 的图像生成不是任意分辨率都稳定，最好按官方支持的 bucket 来。

我最终使用的 16:9 测试命令是：

python examples/t2i/inference.py \
  --model_path /root/autodl-tmp/models/SenseNova-U1-8B-MoT \
  --prompt "生成一张中文信息图，标题为 SenseNova-U1 本地部署流程。内容包含四个步骤：创建 Python 3.11 环境、安装 PyTorch CUDA 12.8、下载 SenseNova-U1 模型、运行文生图测试。白底蓝色科技风，16:9 横版，排版清晰，文字尽量清楚。" \
  --width 2720 \
  --height 1536 \
  --num_steps 30 \
  --cfg_scale 4.0 \
  --device cuda \
  --dtype bfloat16 \
  --attn_backend sdpa \
  --vram_mode balanced \
  --output outputs/sensenova_u1_deploy_flow_2720x1536.png

生成结果如下：

这一版使用官方 16:9 bucket，比前面的 1024x1024 测试更符合模型推荐分辨率。它也进一步证明：在 CUDA 环境下，只要分辨率和参数设置合理，SenseNova-U1 的文生图流程可以完整跑通。

用 SenseNova-U1 生成文章封面

最后我又让它生成了一张文章封面。提示词里我明确要求主题是“SenseNova-U1 本地部署实战”，画面包含 GPU 服务器、MacBook、Python 3.11、CUDA 12.8、PyTorch 2.8、Hugging Face、MPS OOM、vGPU 等关键词。

命令如下：

python examples/t2i/inference.py \
  --model_path /root/autodl-tmp/models/SenseNova-U1-8B-MoT \
  --prompt "生成一张中文技术博客封面图，主题是 SenseNova-U1 本地部署实战。画面主体是一台发光的 GPU 服务器和一台 MacBook，通过蓝色数据流连接，背景是深色科技空间，漂浮着 Python 3.11、CUDA 12.8、PyTorch 2.8、Hugging Face、MPS OOM、vGPU 这些关键词。标题文字：SenseNova-U1 本地部署实战。副标题文字：从 Mac 尝试到 CUDA GPU 跑通。整体风格高级、清晰、科技感强、信息图海报感、16:9 横版、构图有冲击力、中文标题尽量清晰。" \
  --width 2720 \
  --height 1536 \
  --num_steps 40 \
  --cfg_scale 4.0 \
  --device cuda \
  --dtype bfloat16 \
  --attn_backend sdpa \
  --vram_mode balanced \
  --output outputs/sensenova_u1_article_cover.png

终端生成过程：

最终封面图我放在文章开头，也再贴一次：

这张封面图的整体完成度比我预期更好：主题明确，GPU 服务器、Mac、本地部署这些元素都能和文章内容对应起来，中文标题也足够醒目。对我来说，它已经不只是“跑通模型”的证明，而是可以直接服务文章表达的结果图。

这次部署我得到的几个结论

第一，网页版适合快速验证创意。本地部署前，我先用网页版生成了信息图和贴纸。如果这个阶段效果不值得继续投入，本地部署其实没有必要。

第二，Mac 可以做环境验证，但不适合当前 8B-MoT 完整生成推理。我的 Mac 上完成了 Python 3.11 环境、依赖安装、模型下载和脚本启动，但 MPS 在加载模型阶段就接近 18GB 上限并 OOM。--vram_mode low 又依赖 CUDA/XPU，不支持 MPS。

第三，CUDA 服务器是当前最稳路线。只要 PyTorch 版本、CUDA 版本、Python 版本对齐，部署体验明显顺畅。我的环境里 torch==2.8.0+cu128、CUDA 12.8、RTX 3090 能跑通本地推理。

第四，模型下载要提前规划。SenseNova-U1-8B-MoT 文件不少，直接在线加载容易受网络影响。我更推荐先用 huggingface-cli download 下载到数据盘，再用本地路径加载。

第五，分辨率要尊重官方 bucket。像 1360x768 这种看起来标准的 16:9，并不一定适合模型内部 patch 逻辑。官方 16:9 bucket 是 2720x1536，使用非 bucket 分辨率可能会在 patchify 阶段报错。

最后总结

这次折腾下来，我最大的感受不是“终于生成了一张图”，而是对 SenseNova-U1 的部署边界有了更清楚的判断。

我认为 SenseNova-U1 最有价值的点不是单张图是否完美，而是它把理解、生成、编辑、交错图文这些任务放在统一模型路线里。对于开发者来说，这意味着后续不一定要为每个多模态任务拼不同模型和不同服务，而是有机会围绕一个统一模型做应用层封装。

当然，从这次实测看，它也不是“无脑本地跑”的模型。Python 版本、CUDA 版本、模型下载、显存、分辨率 bucket，每一项都可能成为部署门槛。我的建议是：

如果只是体验能力，先用网页版。
如果是 Mac 用户，先把它当成环境适配和失败分析样本，不要期待轻松跑满。
如果要真正复现本地推理，优先选择 Linux + NVIDIA CUDA。

这条路线最终是跑通的，而且中间踩到的问题也比较有代表性。对我来说，这比单纯贴一个“成功生成”的结果更有意义。

看我你就不焦虑了,程序员！失踪人口回归，我去干嘛了！！！！

程序员三时 — Fri, 22 May 2026 16:07:38 GMT

看了一下我掘金最后一篇文章更新时间，已经是在两年前了，很久没有在掘金上去更新了，我加入掘金社区是在2019年，中间断断续续有更新一些文章和学习内容。断更很久了，因为我失业了很久

记得上一份工作还是在北京工作，一个很偶然机会得到工作机会然后从成都去了北京，这份工作依稀记得在2024年11月出初结束，没错我是被裁员了

在外漂泊有7到8年吧，我后面选择了会老家，于是我会武汉了，距离现在2026年5月22号，已经过去一年半了，

我还没有找到工作，因为需要定居，于是我在武汉买了房子（ps本来我不想买，可是爸妈说租房子不如买房子，我确实也没地方住），存款也已经不多了。

当然中间是有摆烂一段时间，再加上AI不断爆火更新我陆续开始找，可是好像一直没有勇气迈出哪一步，我一直觉得我没有准备好，中间自己也有接一些私活，但是只能说维持生活，可是也越来越难了。

我歇息久了，我就感觉我就不想上班了，每天除了吃就睡，晚上睡不着，白天睡不醒，一天饿了才会吃，偶然发疯，本来说想趁着这段时间，学习一下AI相关的东西的，可是断断续续也没有学进去什么，

但我意识到我不能再这么颓废下去了，我一直拿准备好再去面试当借口一天拖拉一天，我知道这样我可能永远都准备不好，永远不可能迈出那一步。

我是JAVA后端开发，可以给我一些建议，AI方面 AI agent 开发可以吗，还是其他工作岗位和编程相关性的，或者JAVA后端在武汉好找工作吗，有什么经验吗，在武汉工作伙伴们，我今年30了，学历大专，在线急急急。。。。。

Gemini3.5Flash前端是真的强！

甲维斯 — Fri, 22 May 2026 09:35:42 GMT

Gemini 前端厉害，是公认的！但是没想到 3.5 Flash 这么厉害！（抱歉~有点冒犯到前端和设计师了）

“桃花影落飞神剑，碧海潮生按玉箫。” ——黄药师《射雕英雄传》

最近我有点“复古”，在研究“武侠”！

然后就想着让 AI 帮我做一个网页，可以整理出金庸、古龙的武侠作品，以及其中的人物、武功、兵器、战役、图谱。

因为这几天在高强度测试 Gemini 3.5 Flash，所以这个任务自然是交给它了。

它第一个版本就惊艳到我了！

风格设计相当出色，而且贴合主题，内容规划也非常到位，字体选得也很赞，配色也不错！* 制作过程也极快。*

就几句话的事情，整个前端设计已经做得八九不离十了！

根本不用费心和设计师沟通，规划不同页面，然后搜集各种数据，然后反复调整，反复改稿，然后再找一个前端工程师把设计稿变成网页。

现在就一个 Gemini，几分钟功夫，全部搞完！

它的页面构思是非常全面的，基本的内容展示逻辑都考虑到了。

下面我就来展示一下细节，最后说一下，我是如何指挥 Gemini 3.5 Flash 生成这个网页的！

首页

一个红色的特殊字体的“江湖百晓生”点明网站主题。

然后下面金色文字：“知天下人 + 悉天下兵 + 辨天下武 + 记天下事”！

非常形象地概括了主要内容。

接下来是武侠世界的名人名言。看到这些熟悉的对白，脑海里立马就会复习哪些我们耳熟能详的片段。

底部还有一个搜索框。可以搜寻侠客、绝技、兵器、宝典。

然后还做了分卷二、分卷三，可以分屏展示！

这个整体感觉太好了，这绝对不是简单的排列组合。

而是充分理解了中国武侠，融会贯通之后，才会有的设计。

你看这些文字描述，全是那透着古味儿的武侠专有名词。

藏经秘阁

这一部分主要展示金庸和古龙的武侠作品。

顶部做了金庸作品集和古龙系列集的分类。下面是一本书一个卡片。卡片设计也很有古风韵味，看起来就很像一本书。右侧竖屏的书名，左边的书线。然后每本书上有一句话和书的概要。

比如射雕英雄传的：“侠之大者，为国为民”；

神雕侠侣的：“问世间情为何物，直教人生死相许”！

天龙八部这个：“飞雪连天射白露，笑书神侠倚碧鸳” 好像是错乱了，这是金庸的书名集合！

点击书本还可以展开：

展开之后可以看到：

书里面有哪些角色
出场的神兵是什么
经典武学有哪些

群侠风云

这一部分主要就是小说中出现的人物。

下面可以看到我们熟悉的：

丐帮：萧峰
大理段氏：段誉
逍遥派：虚竹
丐帮：郭靖
桃花岛岛主：黄蓉
古墓派：杨过
古墓派：小龙女
明教：张无忌

等等等等。

每一个人物一张卡片，卡片里面包含了以下内容：作者来源、所属派别、相关标签。

点开每个人物之后，就可以看到他的详细信息。

比如我们的萧峰，降龙大侠北乔峰！

侠客生平：

他曾任丐帮帮主，为人豪迈飒爽，智勇双全，世人尊称为“北乔峰”。

江湖语录：

我萧峰大好头颅在此，谁来取之？阿朱就是阿朱，四海列国，千秋万载，就只有一个阿朱。

人物纠葛：

结拜兄弟：段誉、虚竹，挚爱：阿朱

右边还有一个人物雷达图，哈哈！

兵器谱

这部分主要展现小说中的兵器。

因为百晓生这个角色主要源于古龙的小说，所以这部分首先放的是“百晓生兵器谱”。在古龙的小说中：

天机棒（排名第一）
子母龙凤环（排名第二）
小李飞刀（排名第三）

继续往下翻就可以看到其他的兵器了。

这个兵器也进行了分类，可以选金庸还是古龙，甚至还细分为：剑、刀、暗器、奇门、防具等！每件武器都有介绍以及锋芒值。

奇功奥义

这一部分就介绍小说中的武功秘籍吧。

武功秘籍也是卡片形式的，可以展开和收起，同时也做了分类和筛选。

比如第一个是金庸掌法类的降龙十八掌，里面说到源自历代丐帮帮主的传承。经典招式：

亢龙有悔
飞龙在天
见龙在田
神龙摆尾
潜龙勿用
双龙取水

牛牛牛～～学会了！

风云战役

这部分显示的就是小说中的名场面。

这里面的布局还挺有特色的，采用那种类似时间线和节点的方式，左边一个、右边一个交叉显示。

这里放在第一个的是金庸的华山论剑。对这个事件做了说明，然后列出了参战的风云人物。

这里提到参与的人有：王重阳、黄药师、欧阳锋、段智兴、洪七公、郭靖、杨过。

这个细节应该是对的吧？

除了这个之外，还有很多名场面，比如“决战紫禁之巅”。

参战人物有：西门吹雪、叶孤城、陆小凤等。

还有“决战光明顶”。

六大正道门派围攻明教总部光明顶，参战人物有：张无忌、灭绝师太等。

江湖图谱

这部分主要就是说人物关系。

比如我们的丐帮帮主萧峰，他的人物关系包括：

结拜兄弟：段誉、虚竹
挚爱：阿朱
另外还有一些灰色的部分，好像是一些推荐的人物。

点击某个人物之后，这个图就会立马切换成新的人物关系图。

除了上面各种功能之外，还包含了两个主题，以及右下角的背景音切换功能。

整体看下来，项目已经非常完善了：

每个功能模块都已经具备
每个页面设计都已完成
相关的内容填充也都很到位

接下来只要稍微完善一下，把数据补充完整就 OK 了。

我是只抽了一次卡，直接就抽到了比较满意效果，所以就没有再继续抽了。

感觉多抽抽还能抽出很多宝藏！

制作过程

光分享结果不是我的风格，所以下面带大家来体验一下，我是怎么制作的。

我使用的工具就是谷歌最近发布的 Antigravity 2.0。

操作很简单：打开软件，创建一个文件夹，开始提出自己的想法。

然后，Gemini 就帮我做了一些设计，提供了一些方案供我选择。

我为“江湖百晓生”网站制定了一份详细的实施计划。

它涵盖了技术选型（Vite + React + CSS）、视觉风格规范（水墨风、自定义雷达图、落叶动效）以及详尽的金庸与古龙小说/人物/神兵/武功数据结构。

请您查看实施计划，并在继续之前协助确认以下几个关键点：

视觉风格倾向：您更喜欢水墨暗黑风（黑/深灰色背景、朱砂红与金色点缀，极具武侠神秘感）还是古风宣纸风（淡黄/米色宣纸质感背景、墨黑与棕色线条，偏向传统古朴画卷）？

门派可视化：对于各大门派（少林、武当、移花宫、丐帮等）的关系和信息展现，您希望是一个图形化的关系网，还是常规的分类卡片？

音乐与音效：我们计划加入优雅的武侠古筝/竹笛背景音乐（默认静音，提供浮动开关），以及按钮悬停/点击时的刀剑出鞘音效，您是否喜欢这种设计？

期待您的反馈！收到您的批准和意见后，我将立刻开始搭建项目并编写数据与界面。

其实你看到它的这个描述时，就知道它已经 get 到你的点了。它已经选择好了技术方案、视觉风格以及内容的排列等。

下面提出了三个问题：

视觉风格：是要选水墨暗黑风，还是古风宣纸风？
门派可视化：你是需要分类卡片，还是关系网？
音乐与音效：计划加入古筝主题背景，并提供浮动开关；此外，按钮选中、点击时会加入刀剑出鞘的音效。

它既然问了，你说我该怎么选呢？我的世界里没有二选一，肯定是全要。

然后它就会自己制作实现方案、任务列表以及总结文档。你只要点执行就好了。

执行完成之后会自动启动服务器，然后你打开这个网址：

http://localhost:5173

这样就可以在浏览器中看到效果了。

当然这个过程也不完全是说全自动完成。

因为你做一个东西的关键在于，它生成的内容和你需要的内容是否能够对齐。当不对齐的时候，你就需要纠正它。

第一阶段计划：
文件：
implementation_plan_phase1.md
内容：初始化 Vite 骨架，建立水墨风视觉设计，构建基础武侠数据库与 Lobby、Characters 等核心组件。

第二阶段计划：
文件：
implementation_plan_phase2.md
内容：实现“宣纸古风”亮色主题与飘落桃花瓣粒子，构建交互式 SVG 江湖人物人际关系网图谱（江湖图谱）。

第三阶段计划：
文件：
implementation_plan_phase3.md
内容：大幅扩充并完善本地数据库（新增 7 位侠客、3 件神兵、6 门武功、4 场战役），打通跳转流转的一致性关系。

所以其实我中间也调整了几轮，它创建了三个计划，然后每个计划里面有一些细节调整。

Gemini 是会把所有的相关文件保存在它自己的目录里面的，然后我就比较喜欢存在我的项目目录里。

所以我让它把所有过程中的相关内容全都保存到我的文档目录存档，这样方便后期的迭代，以及迁移到其他工具或者做后续的回顾。

现在的模型已经很厉害，所以我也没有太多其他可以介绍的。

就是选择一个文件夹，打开一个对话窗口，然后凭借你对业务的理解能力以及想象力，尽情地对话、反馈，然后再对话、再反馈就可以了。具体实施的部分，你是一点都不要去碰，就是让它完成。

我刚才主要是展示了它的设计效果。其实从这次的体验来说，它的逻辑能力（即写代码的工程能力）是比之前的版本有明显的提升的。因为之前的版本很容易写着写着就出错，而这一次基本上写完就没有错误，让它修改的时候时候也是指哪打哪，跟随感比较好。

现在好像配额也多了！

收集大量资料，改了这么多页面内容，写了好几个文档，居然只消耗了 2/5，马上又可以重置了！

哎，既然如此，是不是要续一波？至少前端很强，后端还行，速度很快，是吧！

手把手教你写一个 AI Skill，让 AI 真正学会你的工作流

程序员小寒 — Fri, 22 May 2026 00:36:14 GMT

Skill 可以理解成 AI 的“专业能力模块”。

它不是临时 prompt，也不一定要联网调用外部工具。更准确地说，它是一个文件夹，把某类任务里的经验、规则、操作流程和注意事项都收进去，后面反复用。

比如你经常让 AI 写周报，每次都要提醒它：

不要写得太空。
不要虚构数据。
要先整理工作内容。
要写成果、问题和下周计划。
语言正式一点。

像这种每次都会重复提醒、又很容易沉淀成规则的东西，就适合做成 Skill。

下面我用“工作总结写作”举例，创建一个叫 work-summary-writing 的 Skill。

一个 Skill 长什么样？

一个最简单的 Skill，其实只需要一个 SKILL.md 文件：

work-summary-writing/
└── SKILL.md

更完整的 Skill 还可以包含这些目录：

work-summary-writing/
├── SKILL.md
├── scripts/
├── references/
└── assets/

不同目录的作用不一样：

目录	作用
`SKILL.md`	必需文件，描述 Skill 什么时候触发，以及触发后怎么做
`scripts/`	放可重复执行的脚本
`references/`	放较长的规则、规范、接口文档或业务资料
`assets/`	放模板、图片、字体、示例文件等输出素材

刚开始不用急着把目录搭得很完整。先把 SKILL.md 写清楚，让它能触发、能稳定完成任务，第一版就够用了。

第 1 步：确定这个 Skill 解决什么问题

别一上来就写“万能写作 Skill”。

Skill 越泛，越容易失控。比如：

description: "帮助用户写东西"

这个描述太宽。写文章、写邮件、写代码注释、写广告文案、写产品需求文档，都可能触发它。模型最后反而不知道该按哪套规则走。

我们这次只解决一个具体场景：

当用户需要写工作总结、周报、月报、季度总结、年度总结、项目复盘或阶段性汇报时，帮助用户把零散信息整理成一篇总结。这篇总结要结构清晰、重点明确、表达正式自然。

边界说得越清楚，Skill 越稳定。

第 2 步：创建 Skill 目录

不同 AI 工具放 Skill 的位置不一样。

以 Codex 为例，个人全局 Skill 通常放在：

~/.codex/skills/

如果我们要创建 work-summary-writing，目录结构就是：

~/.codex/skills/work-summary-writing/
└── SKILL.md

可以用命令创建目录：

mkdir -p ~/.codex/skills/work-summary-writing

如果你使用的是 Claude Code，目录可能是：

~/.claude/skills/work-summary-writing/

关键不是路径本身，而是要放进对应 Agent 能识别的 Skill 目录。

第 3 步：写 FrontMatter

SKILL.md 开头需要一段 YAML FrontMatter：

---
name: work-summary-writing
description:  撰写、润色或整理中文工作总结类文档时使用，包括周报、双周报、月报、季度总结、半年/年度总结、项目复盘、阶段性汇报、述职报告、工作小结等。当用户说"帮我写个周报"、"整理一份月度工作"、"年终总结"、"项目复盘"、"做汇报材料"、"述职"，或扔过来一堆零散工作记录要求"总结一下"、"整理成报告"时，都要主动启用。该技能用于帮助用户把零散工作内容整理成结构清晰、重点明确、表达正式自然的总结文本。
---

这里最重要的是两个字段：

字段	作用
`name`	Skill 的名字，建议使用小写英文、数字和连字符
`description`	Skill 的触发条件和能力说明

很多人会低估 description。

它不是写给人看的简介，而是给 AI 判断“什么时候该加载这个 Skill”的依据。只有 Skill 被触发后，AI 才会继续读正文。触发条件如果只写在正文里，模型可能根本看不到。

所以 description 里至少要说清楚三件事：

这个 Skill 能做什么。
适合什么场景。
用户说哪些话时应该触发。

不要写成：

description: 帮助写总结

这太短，也太模糊。

第 4 步：把流程写成可执行步骤

Skill 更像操作手册，不是理念宣言。

不要只写：

写得专业、自然、有逻辑。

这类话方向没错，但模型不好执行。更稳的写法，是把任务拆成一步一步的动作。

下面是一个完整的 SKILL.md 示例：

---
name: work-summary-writing
description:  撰写、润色或整理中文工作总结类文档时使用，包括周报、双周报、月报、季度总结、半年/年度总结、项目复盘、阶段性汇报、述职报告、工作小结等。当用户说"帮我写个周报"、"整理一份月度工作"、"年终总结"、"项目复盘"、"做汇报材料"、"述职"，或扔过来一堆零散工作记录要求"总结一下"、"整理成报告"时，都要主动启用。该技能用于帮助用户把零散工作内容整理成结构清晰、重点明确、表达正式自然的总结文本。
---

# 工作总结写作

## 写作步骤

### 1. 明确总结范围

先判断总结的时间范围、使用场景和目标字数，例如：

- 周报
- 月报
- 季度总结
- 年度总结
- 项目阶段总结
- 个人工作复盘

如果用户没有说明时间范围，可使用“本阶段”作为默认表述。

如果用户没有说明字数，默认生成 800-1200 字左右的工作总结。

### 2. 提炼核心工作

从用户提供的信息中提取主要工作内容。

优先识别：

- 负责了什么任务
- 推进了哪些项目
- 解决了哪些问题
- 参与了哪些协作
- 完成了哪些交付

### 3. 整理工作成果

将工作内容转化为结果表达。

尽量补充：

- 完成情况
- 进展状态
- 产生的价值
- 效率提升
- 问题解决效果
- 可量化数据

如果用户没有提供数据，不要编造，可使用“提升了工作效率”“推动了项目进展”等稳妥表达。

### 4. 分析问题与不足

客观总结工作中存在的问题。

可以从以下角度整理：

- 进度是否受阻
- 沟通是否充分
- 流程是否顺畅
- 方案是否还有优化空间
- 个人能力是否需要提升

表达要克制，不夸大问题，也不回避问题。

### 5. 提炼经验与反思

总结本阶段获得的经验。

重点写：

- 哪些方法有效
- 哪些流程可以复用
- 哪些协作方式值得保留
- 后续可以如何改进

### 6. 制定下一步计划

根据前文内容，提出后续计划。

计划应具体、可执行，例如：

- 继续推进某项任务
- 优化某个流程
- 提升某项能力
- 完成某个交付
- 加强沟通协作

## 字数要求

- 优先遵循用户明确提出的字数要求。
- 如果用户没有提出字数要求，默认生成 800-1200 字。
- 如果用户要求“简短”“简单”“概括”，控制在 300-600 字。
- 如果用户要求“详细”“完整”“正式”，控制在 1200-2000 字。
- 不要为了凑字数重复表达。
- 不要为了压缩字数删掉关键事实。

## 推荐结构

```text
一、总体情况
简要说明本阶段的工作重点和整体完成情况。

二、主要工作
分条说明完成的重点事项。

三、工作成果
总结取得的结果、进展或价值。

四、问题与不足
客观说明存在的问题和改进空间。

五、经验总结
提炼本阶段的收获和方法。

六、下一步计划
说明后续重点工作安排。
```

## 注意事项

- 不要虚构关键事实、数据、项目名称或成果。
- 用户提供的信息不足时，可以使用通用表达，但应避免写得过满。
- 表达要正式、自然、简洁，避免口号式语言。
- 多写具体行动和实际结果，少写空泛态度。
- 总结个人工作时，突出职责和贡献，但不要过度夸大。
- 总结团队工作时，注意使用“我们”“团队”等表述。
- 问题与不足要真实可改进，不要写成严重失误。
- 下一步计划要和前文问题、成果形成呼应。

## 输出要求

默认输出一篇完整工作总结。

如果用户只要求框架，则只输出结构和要点。

如果用户提供了原始素材，应优先基于素材改写，不随意扩展事实。

写到这里，一个最小可用的 Skill 就完成了。

第 5 步：测试 Skill 是否能触发

保存后，可以用接近真实场景的提示词测试：

帮我写一份本周工作总结。

或者：

把下面这些工作记录整理成月报，正式一点，控制在 1000 字左右。

测试时我一般看三件事：

是否会按工作总结场景响应。
是否遵守结构、字数和注意事项。
是否在信息不足时乱编数据。

经常不触发，就先改 description。

能触发，但输出不稳定，就改正文里的“写作步骤”“注意事项”和“输出要求”。

第 6 步：什么时候需要 scripts、references 和 assets？

不是每个 Skill 都需要额外目录。

像“工作总结写作”这种偏写作和判断的 Skill，通常一个 SKILL.md 就够。

任务变复杂之后，再考虑拆资源。

需要 scripts 的情况

如果某个操作需要稳定执行，就别让 AI 每次重新想办法。

例如：

markdown-mermaid-to-images/
├── SKILL.md
└── scripts/
    └── convert_mermaid.py

这类任务涉及文件扫描、图片导出、路径替换。交给脚本，比写一堆自然语言规则可靠。

需要 references 的情况

如果有大量规则、规范、接口文档或业务知识，就放到 references/。

例如：

contract-review/
├── SKILL.md
└── references/
    └── clause-checklist.md

SKILL.md 只写核心流程，并说明什么时候读取参考资料。

需要 assets 的情况

如果最终产物需要模板或素材，就放到 assets/。

例如：

slides-builder/
├── SKILL.md
└── assets/
    └── company-template.pptx

这样 AI 不用每次重新创建模板，也更容易保持统一样式。

手写 Skill 的常见问题

手写 Skill 很适合理解原理，但也容易踩坑。

1. description 太宽泛

错误示例：

description: 写作助手

这个描述几乎什么都能触发，边界太宽。

更好的写法：

description: 撰写、润色或整理中文工作总结类文档时使用，包括周报、双周报、月报、季度总结、半年/年度总结、项目复盘、阶段性汇报、述职报告、工作小结等。当用户说"帮我写个周报"、"整理一份月度工作"、"年终总结"、"项目复盘"、"做汇报材料"、"述职"，或扔过来一堆零散工作记录要求"总结一下"、"整理成报告"时，都要主动启用。该技能用于帮助用户把零散工作内容整理成结构清晰、重点明确、表达正式自然的总结文本。

2. 只写原则，不写步骤

错误示例：

## 要求

写得专业、自然、有深度。

更好的写法，是把“专业”拆成动作：

先判断总结范围。
再提炼核心工作。
然后整理成果。
接着写问题与不足。
最后写经验和计划。

3. 把所有东西都塞进 SKILL.md

SKILL.md 最好保持精简。

内容越来越长时，通常就该拆了：

长规范放 references/。
重复操作放 scripts/。
模板素材放 assets/。

4. 没有写反例和禁区

很多输出问题，不是 AI 不知道该做什么，而是不知道什么不能做。

例如工作总结里必须明确：

不要虚构数据。
不要写口号。
不要把小问题写成严重事故。
不要为了凑字数重复表达。

限制写得越清楚，输出越稳定。

接下来：用 skill-creator 自动创建

手写过一遍之后，再看 skill-creator 就顺很多。

skill-creator 也是一个 Skill，只是它专门负责创建和更新 Skill。目录结构、FrontMatter、资源该不该拆，它会帮你一起处理。你不用每次都从空白文件开始。

github地址：github.com/anthropics/…

安装 skill-creator：

npx skills add https://github.com/anthropics/skills --skill skill-creator

你可以直接这样要求 claude code:

使用 skill-creator，帮我创建一个 work-summary-writing skill。

目标：
当用户需要写工作总结、周报、月报、季度总结、年度总结、项目复盘或阶段性汇报时触发。

能力：
1. 判断总结范围和字数要求。
2. 从零散工作记录中提炼核心工作。
3. 整理工作成果、问题不足、经验总结和下一步计划。
4. 输出正式、自然、结构清晰的工作总结。

注意事项：
1. 不要虚构关键事实、数据、项目名称或成果。
2. 信息不足时使用稳妥表达。
3. 避免口号式语言。
4. 下一步计划要具体可执行。

位置：
安装到全局 Claude skills 目录。

这种请求比“帮我创建一个写周报 Skill”稳定得多。边界给清楚了，skill-creator 才知道该往哪里收、哪里不能展开。

skill-creator 会帮你做什么？

skill-creator 不只是生成一个空文件夹。

它会从“另一个 AI 以后怎么用这个 Skill”的角度，帮你把这些事情过一遍：

理解这个 Skill 要解决什么问题。
整理触发条件和真实使用场景。
规划是否需要 scripts/、references/、assets/。
创建 Skill 目录和 SKILL.md。
写好 name、description 和正文流程。
必要时补充资源文件。
检查 Skill 结构是否完整。
根据真实使用结果继续迭代。

换句话说，手写时你要自己操心的细节，skill-creator 会替你检查一轮。

为什么要用 skill-creator？

手写适合学习原理。真要长期用，我更建议交给 skill-creator 起草和迭代。

原因主要有四个。

1. 它更懂 Skill 的结构

一个 Skill 不只是写一段 prompt。

它需要考虑：

name 是否规范。
description 是否能准确触发。
正文是否是可执行流程。
是否缺少注意事项。
是否应该拆分资源目录。

这些细节手写时很容易漏掉。

2. 它能减少触发错误

低质量 Skill 最常见的问题，就是 description 写得太宽，或者太窄。

太宽会误触发，太窄会不触发。

skill-creator 会提醒你把能力、场景和触发词写清楚。比如别只写“处理合同”，要写成“当用户要求检查合同、总结合同风险或整理关键条款时使用”。

3. 它会帮你判断资源怎么拆

很多人第一次写 Skill，会把所有规则都塞进 SKILL.md。

短期能用，时间一长就会臃肿。

skill-creator 会根据任务判断：

是否需要脚本保证稳定执行。
是否需要参考资料保存长规则。
是否需要模板或素材支持最终输出。

这就是渐进加载：常用规则放正文，长资料按需读取，重复操作交给脚本。

4. 它适合持续迭代

好的 Skill 通常不是一次写完的。

真实使用后，你会发现它可能有这些问题：

某些提示词没有触发。
输出格式不稳定。
经常编造不存在的数据。
处理复杂输入时漏步骤。
和其他 Skill 的边界冲突。

这时可以继续让 skill-creator 检查和更新：

使用 skill-creator 检查这个 skill 是否合格：
~/.claude/skills/work-summary-writing

重点检查：
1. description 是否能准确触发。
2. SKILL.md 是否过长。
3. 写作步骤是否可执行。
4. 注意事项是否覆盖常见错误。
5. 是否需要拆分 references 或 assets。

这比临时修一句 prompt 稳得多。

手写和 skill-creator 怎么选？

可以按这个规则判断：

场景	建议
第一次学习 Skill	手写一遍
只需要一个很小的个人规则	手写也可以
要创建长期复用的 Skill	用 `skill-creator`
Skill 涉及脚本、模板、参考资料	用 `skill-creator`
需要检查触发条件和目录结构	用 `skill-creator`
需要迭代已有 Skill	用 `skill-creator`

我的建议是：先手写一个最小版本，搞清楚 name、description、正文流程和注意事项分别在干什么。之后要创建正式 Skill，再交给 skill-creator。

小结

写 Skill 的重点，不是把 prompt 写长。真正要做的，是把高频任务沉淀成一套能触发、能执行、后面还能维护的工作流。

一个好 Skill，至少要回答四个问题：

什么时候触发？
触发后按什么步骤做？
输出应该长什么样？
哪些事情不能做？

手写能帮你理解底层结构。skill-creator 则适合把这套结构做完整，并且在后续使用中持续修。

第一版 Skill 不需要完美。先让它在真实任务里跑起来。哪里触发错了，就补触发条件；哪里输出跑偏了，就补规则和反例；哪里靠文字说不稳，就拆资源、加脚本。 Skill 是这样一点点变强的。

往期回顾

AI Harness 企业级落地实践（一）

Karl_wei — Thu, 21 May 2026 07:43:06 GMT

一、前言

今年 AI 圈是非常躁动的，除了全民养龙虾，Harness 也在技术圈掀起了不小的波澜。

与open claw不同的是，Harness 不是一个服务大众的产品。通俗来说，Harness 是将工程学的思维，落地成范式束缚于Agent上，让Agent能够更规范、更稳定的工作。

Harness是什么？

想象一下在广袤的草原上，一群骏马飞快的驰骋着，它们就是 AI，有时候难免会跑偏。此时一位猛男，拿着马具跳到马背上，三下五除二就让骏马一直沿着正确的道路飞奔！

这个马具就是 Harness！👉 套马的汉子，你威武雄壮~

关于Harness更具体的定义可以参考以下文献: OpenAI Harness 深度长文、Harness Engineering即控制论

今天笔者的核心：详细拆解 Harness 工程的设计和落地

同时，也会把这套实践开源，让每个开发者都能快速用上 Harness，解决“万事开头难”的哲学难题

快速、低成本给自己的项目加上Harness范式
享受 openSpec +oh my xcode带来的高质量方案设计和代码交付
轻易定制建设更适合自己团队的Harness项目工程

开源项目地址：github.com/WxqKb/cow-h…

你的 [Star] 将是我的核动力✨

二、基础软件工程理念

Software Process Improvement（SPI）

前面我们讲到，Harness 简单理解就是让AI 大模型能严格按照软件工程的体系，执行方案分析设计、代码开发、测试验证等流程，从而高效完整的完成工作。

这次 Harness 的搭建，使用软件工程中一个比较标准的体系： 《软件过程改进闭环》

立项决策 → 需求规划 → 评审规范 → 实施验证 →复盘改进

在整个工程中，我们把复杂的需求拆解为以下环节，从而契合CMMI 与敏捷Scrum 的迭代研发标准框架：

Decisions → Plans → Reviews → Specs → Verifications → Retros

	软件工程标准专业名词	所属体系
decisions	基线决策 / 变更决议 / 技术决策	CMMI、敏捷
plans	迭代规划 / 项目计划 / 里程碑计划	敏捷Scrum、软件工程
specs	需求规格说明(SRS) / 技术规范 / 基线规范	软件工程、CMMI
reviews	同行评审 / 阶段评审 / 质量门禁评审	CMMI、ISO软件工程
verifications	验证 Verification (V)	CMMI
retros	过程复盘 / 迭代回顾 / 流程改进回顾	Scrum、SPI

三、框架选型和落地

1. 技术选型

Harness 的搭建，需要把这些软件流程落成约束范式，把每一个环节都拆细，比如：

需求理解阶段：用头脑风暴（brainstorming）的模式，让AI 覆盖更多的边界场景思考出来
技术方案设计：我们会用 superpower（brainstorming、writing-plans），通过不断的追问，从顶层设计、全栈链路、风险前置等维度，与研发人员进行确认，边界场景覆盖完整
方案评审：严格的过程，指定 superpower 对应的技能，来进行智能评审，对方案进行评分。同时设定门禁，必须由研发人员同意才能继续往下实施
任务实施：拆分完的 Task，我们通过 omx、using-git-worktrees 进行编排。它会自动把具体的任务分配给合适的 Agent，达到更高效的编排和更完美的实施
等等……

2. 脚手架设计

cow-harness/
├── README.md                  
├── project.profile.md         # AI 生成的项目基础信息画像
├── context-map.md             # AI 生成的项目模块/上下文边界地图
├── project.verification.md    # AI 生成的项目级验证规则
│
├── core/                      # 通用 Harness 规则（核心约束）
│   ├── harness.md             # Harness 核心理念与总体约束
│   ├── routing.md             # 任务路由表与分发规则
│   ├── artifacts.md           # 过程产物格式与存放规范
│   ├── verification.md        # 验证门禁与完成标准
│   └── runbooks.md            # 各类任务的标准操作手册
│
├── init/                      # 新项目初始化
├── entrypoints/               # AI 入口文件模板（CLAUDE.md 等）
├── adapters/                  # 各编程工具适配模板（.cursor/ 等）
├── scripts/                   # 内部脚本，初始化会调用
└── artifact-templates/        # 过程产物模板

core层是核心的约束
- routing 路由表会判定用户的任务属于 SPI 的哪个流程，进而决定使用什么工具和流程
- runBooks 执行手册会说明哪些环节使用什么技能
- artifacts 会约束过程产物的规范，并且沉淀成项目级别的知识库；
- verification 会规定验证和准入标准
init 层，支持一句话，让 AI 在你的项目中部署 Harness，将工具适配层、入口文件等投射到你的项目根目录中。
- 同时阅读你的项目，生成属于你项目的信息画像。
- 这一步非常重要，完成初始化后，你在让 AI Agent 工作的时候，自然就会按照Harness 的约束去执行任务了
entrypoints，AI 执行指令时是会先找到项目目录下的入口文件。
- 比如 gpt 会加载 AGENT.md，Claude 会加载 CLAUDE.md
- init 的时候，会把入口文件投射到项目中，重新启动 AI Agent，查看默认上下文，你就会发现对应的入口文件都被加载进去了

adapters：AI 编码工具的适配层，需要指定主流工具严格进入入口文件，进入 Harness 约束

3. 一些粗浅的设计理念

Harness 其实也是软约束，init 做好最基础的工作，达到可用状态
文件投射到项目本地，最大的好处是**你完全可以根据自己的实现，去修改 Harness 约束**
没有提供 sdk、npm 包等接入方式，最直接把cow-harness 拷贝到你的项目中，自由度完全开放给开发者。我们希望，每个人都能深度参与到对 AI 的管控，直到成为你团队内完全可复用的 AI 规范
长期来看，大模型的能力提升会弱化 Harness 的作用。但**约束的设计思维，必然与时俱进**

四、接入步骤

项目拷贝
把cow-harness 项目 fork/ download 下来，通过 git submodule 引导你的项目中（或者直接把cow-harness 文件夹放在项目中）
阅读 README，执行 init，这一步 AI 会：

安装相关的 skills
生成项目画像
投射必要的文件到本地
创建产物结构目录

不要手工阅读和执行每一步，请务必相信 AI 比我们做的好。直接把下面这段话发给 AI：

请先读取 cow-harness/README.md 和 cow-harness/init/bootstrap.prompt.md。
这是一个新项目刚接入 Agent Harness，请按 Harness 初始化流程处理：
1. 从 cow-harness/entrypoints/ 投影根目录 AI 入口文件。
2. 从 cow-harness/adapters/ 投影工具适配目录。
3. 创建 .ai-runtime-artifacts/ 及其子目录。
4. 如需安装或检查 AI runtime，请先说明会修改哪些本机环境，然后由你执行 cow-harness/scripts/install-ai-skills.sh。
5. 读取 cow-harness/init/project-profiler.prompt.md。
6. 扫描当前项目，生成或更新 cow-harness/project.profile.md、cow-harness/context-map.md、cow-harness/project.verification.md。
7. 由你运行 cow-harness/scripts/harness-check.sh。
8. 汇总推断项、待确认项和验证结果。

3. 开始执行任务
重启 AI 终端，开启你的 cow-harness 之旅

五、自我 QA 环节

接入之后，是不是所有任务都必然会走到 harness 约束中？
答：理论上是的，但是我们会判断这个任务的量级，小任务会直接放行
harness 的约束能否达到 100%？
答：否！harness 也是软约束，你甚至可以理解成是 prompt 超集，在实践中我们正常的提问都可以命中，同时我们在产物中明确说明了推理过程中使用了那些技能
这个项目的目的是？
答：核心只有一个：帮助部分同学解决 Harness “万事开头难”的问题。这是个非常简单的基础建设，你开始之后可以轻松随意植入自己想法，去约束 AI，加入新的技能包
如何加自己的技能包？
答：能用开源的尽量用开源的，社区的 Star 和实践踩坑，能让你少走很多弯路。内部自定义的 Skills，请用 skills-create 这个官方技能包去创建
如果用了 Harness 还是不理想怎么办？
答：如果有更好的，那么换了cow-harness。这终归是一个软约束，模型能力的提升能让我们当下的约束被取代。然而往下探究，当 prompt 约束不够了，就需要干涉到更底层，比如 Agent 内部的编排逻辑，比如构建你公司项目的知识库，等等

六、下一步计划

在实践过程中，笔者会不断优化cow-harness的建设，核心目标是更向一人公司靠拢：

方案输出更精准，接入类似 openspec 的优秀实践，让 specs 的设计更加完整
构建更完整的软件研发全流程：产品 prd 解析、全栈开发流程、AI 测试、监控链路建设等等

Harness 之后，也许我们会再往知识图谱、RAG 向量化、垂类模型训练、Agent 编排逻辑和执行拓扑等方向去学习，分享。

Claude Code Harness 工程：数仓侧落地方案｜得物技术

得物技术 — Thu, 21 May 2026 02:21:32 GMT

一、AI Coding 现状与痛点：为什么需要 Harness

当前使用情况

得物离线数仓各小组已基本完成 AI Coding 工具的覆盖，主力工具为 Claude Code，辅以数据平台的 IDE 插件，应对重复性工作时效率提升明显。

核心痛点

尽管整体提效已显现，但团队在实际使用中暴露出三类结构性痛点。

痛点一：AI 不记得上下文约束，开发过程中反复"失忆"。会话开始时告知了"金额字段单位是千元"，对话进行到一半后 AI 忘了，生成的 SQL 把千元当元用，导致数据差了 1000 倍。这不是偶发问题，而是 Claude Code 的 context compact 机制（上下文压缩）的系统性限制：当对话 token 接近上限（约 95%）时，历史内容被自动压缩为摘要，临时口头说的约束全部丢失。

痛点二：规范执行不稳定，靠记忆兜底的部分最容易出问题。OneData 命名规范、注释三段式、INSERT 必须带 PARTITION 子句......这些规范大家都知道。在项目工期紧张时，人工规范遵守率降至 60%~70%，AI 靠 prompt 记忆的规范遵守率也只有 70%~80%。真正需要的是：把规范从"LLM 记忆中的指导性内容"变成"每次执行时强制检查的护栏"。

痛点三：大型需求开发中，context 很快被撑满，越到后期 AI 越不可靠。复杂需求（大型宽表、大量下游血缘）的典型开发过程：

血缘查询结果（500~3000 tokens） 自测 23 条 SQL 执行结果（5000~15000 tokens） SKILL 规范文件内容（~10000 tokens） 数据比对两表样本（大量行）= context 迅速膨胀 → compact 触发 → 关键约束遗忘 → AI 开始犯低级错误

核心矛盾：越是复杂的需求，越依赖 AI；但越复杂的需求，context 越容易撑满，AI 越容易"失忆"。

从"随手问 AI"到"把能力封装起来"

针对上述痛点，我们沿用了一条反复验证的结论：规范执行是人的短板、AI 的长板；业务判断是 AI 的短板、人的长板。Harness 工程的目标，就是把"执行层"的不稳定因素系统性地消掉：把规范写进 hooks，不再靠 AI 记忆，每次写 SQL 文件后自动触发检查；把迭代约束写进持久化文件，compact 后自动重新注入，不再靠临时口头说；把高 token 操作隔离到 subagent，主 context 只接收摘要，不被过程数据撑满。

二、先搞清楚"Harness"是什么

在 Claude Code 的 update-config skill 描述中有一句话："Automated behaviors require hooks configured in settings.json --- the harness executes these, not Claude"。

Harness = Claude Code 的宿主运行框架，即 Claude Code 客户端本身这个"工具链容器"。它：管理 context window 生命周期；在 LLM 推理循环之外确定性地执行 hooks；协调 subagents 的生命周期；不依赖模型判断，直接执行配置的自动化行为。区别总结：

三、核心问题：compact 到底丢掉什么？

每次数仓开发 context 接近满时，auto-compact 触发（默认 95% 时触发），会把整个对话历史替换为一份摘要，token 缩减到原来的约 12%。哪些内容 compact 后丢失：

数仓场景最痛的点：对话中说的"这次用 OVERWRITE 模式"、"先忽略 field_a 字段" → compact 后全忘；SKILL 文件读了一半，compact 后前几个 step 的内容没了 → Claude 重复询问；自测跑出来 50 行结果，加上血缘查询的几十行表结构 → context 很快膨胀到 compact 阈值。

四、五层防御体系（从简单到复杂）

第一层：写死进 CLAUDE.md（立即可用）

机制：项目根目录 .claude/CLAUDE.md 每次 compact 后从磁盘重新注入，是最可靠的持久化位置。将当前迭代的关键信息写入，格式建议：

# 当前迭代状态（每次迭代手动更新）## 正在开发- 表：db_a.dws_table_a
 版本：V1.0
 node_id：1000000001
 状态：ETL开发阶段（Step 3/8）

## 本次迭代约束- 禁止修改：dwd_table_b（已上线，只读）
 分区字段：partition_dt（格式 yyyyMMdd，不是 dt）
 amount 字段单位：千元（不是元）

## 数仓全局规范
 建表：分区字段必须是 partition_dt string
 禁止：SELECT *，UPDATE/DELETE 无 WHERE
 金额字段用 DECIMAL(20,4)，不用 DOUBLE
 INSERT 必须带 PARTITION 子句

操作规则：进入新迭代时，更新"正在开发"和"本次迭代约束"两节；上线后清空"本次迭代约束"；全局规范长期保留，控制在 100 行以内。

第二层：Auto Memory 自动积累（已在运行）

机制：Claude 自动将跨会话发现写入 ~/.claude/projects//memory/MEMORY.md，每次 compact 后重新注入。数仓场景下主动触发 Claude 写记忆的时机："这张表的 amount 字段单位是千元，请记住"；"field_a 在特定场景下会为空，请记住这个踩坑"；"本次 V1.0 的关键变更是 field_b 逻辑调整，请记住"。Claude 会自动写入 MEMORY.md，下次会话或 compact 后自动恢复。

第三层：hooks 自动验证（核心防御，解决"忘了检查"的问题）

这是解决"每次写完 SQL 自动检查"的关键机制。

配置文件位置

数仓项目根目录/
└── .claude/
    ├── settings.json          ← hooks 在这里配置
    ├── CLAUDE.md              ← 数仓规范上下文
    └── hooks/
        ├── validate_sql.sh          ← SQL 规范自动检查
        ├── block_dangerous_ddl.sh   ← 危险 DDL 拦截
        └── inject_context.sh        ← compact 后重注入上下文

settings.json 完整配置

{"hooks": {"PostToolUse": [{"matcher": "Write|Edit","hooks": [{"type": "command","command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/validate_sql.sh","timeout": 60,"statusMessage": "检查 SQL 规范..."}]}],"PreToolUse": [{"matcher": "Bash","hooks": [{"type": "command","command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block_dangerous_ddl.sh"}]}],"SessionStart": [{"matcher": "compact","hooks": [{"type": "command","command": "cat \"$CLAUDE_PROJECT_DIR\"/.claude/context/dw_conventions.md","statusMessage": "重注入数仓规范..."}]}],"Stop": [{"hooks": [{"type": "prompt","prompt": "检查用户要求的所有任务是否都已完成。如果还有未完成项，返回提示但不要重新开始。检查 stop_hook_active 是否为 true，如是则直接 exit。","model": "claude-haiku-4-5-20251001"}]}]}}

SQL 规范自动检查脚本

.claude/hooks/validate_sql.sh：

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo"$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_input',{}).get('file_path',''))" 2>/dev/null)

# 只处理 .sql 文件
[[ "$FILE_PATH" != *.sql ]] && exit 0
[[ -z "$FILE_PATH" ]] && exit 0

SQL=$(cat "$FILE_PATH" 2>/dev/null)
[[ -z "$SQL" ]] && exit 0

ERRORS=()

# 规范1：禁止 SELECT *echo "$SQL" | grep -iqE 'SELECT\s+\*' && ERRORS+=("CRITICAL: 发现 SELECT *，必须明确列名")

# 规范2：INSERT 必须带 PARTITIONif echo "$SQL" | grep -iqE 'INSERT\s+(INTO|OVERWRITE)'; thenecho "$SQL" | grep -iqE 'PARTITION\s*\(' || ERRORS+=("CRITICAL: INSERT 缺少 PARTITION 子句")
fi# 规范3：DOUBLE 类型金额echo "$SQL" | grep -iqE '\bDOUBLE\b' && ERRORS+=("WARNING: 金额字段建议用 DECIMAL(20,4)，不用 DOUBLE")

# 规范4：UPDATE/DELETE 必须有 WHEREif echo "$SQL" | grep -iqE '\b(UPDATE|DELETE)\b'; thenecho "$SQL" | grep -iqE '\bWHERE\b' || ERRORS+=("CRITICAL: UPDATE/DELETE 缺少 WHERE 条件")
fiif [ ${#ERRORS[@]} -gt 0 ]; thenecho "=== SQL 规范检查失败：$FILE_PATH ===" >&2
  for err in"${ERRORS[@]}"; doecho "  $err" >&2
  doneexit 2
fiecho "SQL 规范检查通过: $(basename $FILE_PATH)" >&2
exit 0

危险 DDL 拦截脚本

.claude/hooks/block_dangerous_ddl.sh：

#!/bin/bash
INPUT=$(cat)
CMD=$(echo"$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_input',{}).get('command',''))" 2>/dev/null)

# 拦截生产表 DROP/TRUNCATE（放行 _dev/_test/_stg 后缀）if echo "$CMD" | grep -iqE '\b(DROP\s+TABLE|TRUNCATE\s+TABLE)\b'; thenif ! echo "$CMD" | grep -qiE '(_dev|_test|_stg)\b'; thenecho "BLOCKED: 检测到生产表 DROP/TRUNCATE 操作，请确认表名是否正确" >&2
    exit 2
  fifiexit 0

hook 通信协议关键规则

关键陷阱：阻断必须用 exit 2，用 exit 1 不会阻止 Claude 继续执行。

第四层：subagents 做上下文隔离（防 context 膨胀）

核心原则：把"高 token 消耗但结果只需要摘要"的操作放到 subagent 的独立 context 中执行。

数仓场景适合下放 subagent 的操作

创建 subagent 文件

.claude/agents/sql-validator.md（SQL 语法验证）：

---
name: sql-validator
description: ODPS/MaxCompute SQL 语法验证与规范检查专用 agent。当用户生成或修改 SQL 文件后需要验证时调用。在独立 context 运行，防止大量验证日志污染主对话。
tools: Read, Bash, Grep, Glob
model: haiku
permissionMode: dontAsk
---

你是数仓 SQL 规范专家，只做验证，不修改文件。

验证项（按优先级）：
1. SELECT * 禁止
2. INSERT 必须带 PARTITION
3. 字段用 snake_case 命名
4. 金额字段用 DECIMAL 不用 DOUBLE
5. 多表 JOIN 必须有 ON 条件
6. 笛卡尔积风险检测

输出格式：
- 状态：PASS / FAIL
- 问题列表（CRITICAL / WARNING / INFO）
- 修改建议（具体到行号）

不超过 50 行，只返回结构化报告。

.claude/agents/dw-explorer.md（防止血缘查询撑爆主 context）：

---
name: dw-explorer
description: 数仓结构探索 agent。当需要大量读取表结构、DDL、字段信息、血缘关系时自动调用，避免大量文件内容污染主 context。只读，不修改任何文件。
tools: Read, Glob, Grep, Bash
model: haiku
permissionMode: dontAsk
---

你是数仓探索专家，只读操作。

当被调用时：
1. 读取指定表的 DDL、字段信息、分区策略
2. 分析上下游血缘（一层）
3. 识别关键字段口径（金额、日期、状态类字段）

输出：不超过 80 行的结构化摘要，包含：
- 表基本信息（层级、粒度、分区策略）
- 核心字段定义（含口径说明）
- 上下游血缘（只列表名，不展开内容）
- 发现的特殊口径或踩坑点

使用方式

在主对话中自然触发：

用 dw-explorer 分析 db_a.dwd_table_a 的结构

对刚生成的 insert_dws_table_a.sql 用 sql-validator 验证

或强制指定（避免 Claude 自行判断）：

@"sql-validator (agent)" 验证 path/to/insert.sql

第五层：SKILL 文件改造（减少 context 消耗）

当前的问题：每次调用 SKILL 文件（01~08.md），内容全部加载进主 context，加速 compact 触发。改造方向：把 SKILL 文件的"执行步骤"提炼成 subagent 指令，subagent 内部读完整 SKILL 文件，主 context 只接收结果摘要；用 path-scoped rules 替代 SKILL 文件中的规范章节，按需加载：

---
# .claude/rules/etl-rules.md
paths:
  - "**/*insert*.sql"
  - "**/*_di.sql"
  - "**/*_df.sql"
---

# ETL 开发规范（按文件路径自动加载）
- 必须有 partition_dt 分区
- INSERT OVERWRITE 前检查分区是否已存在
- 不允许跨库 JOIN

SKILL 文件保持现状，但改变调用方式：不要在主对话中直接触发，而是启动一个 subagent 来读 SKILL 文件执行 ETL，主对话只接收最终产出的 SQL 文件路径。

五、可行落地方案：数仓 Harness 架构

先让我们看一下整体的架构设计（整体架构图）：

这张架构图的核心逻辑是职责分层：不同类型的工作交给最合适的机制去做，而不是全部压在 Claude 的推理循环里。

持久化层解决的是"失忆"问题，任何临时口头说的约束，compact 后都会消失；但写进 .claude/CLAUDE.md 的内容，每次会话启动和 compact 后都会从磁盘重新注入------这是整套方案里最简单也最可靠的一层。

Harness 层（Hooks） 解决的是"规范靠记忆"的问题，PostToolUse hook 在每次写 .sql 文件后确定性触发，不依赖 Claude 有没有记住规范要求；违规时 exit 2 强制阻断，Claude 必须修正后才能继续，规范遵守率从 70%80% 提升到 95%+。

Subagent 层解决的是"context 被撑满"的问题，血缘查询、23 项自测、数据比对这类操作会产生大量 token，放到独立 context 的 subagent 里执行，主会话只接收一份摘要，compact 触发频率预计降低 50%70%。

三层机制分工明确，互不干扰：Hooks 处理"写动作触发的规范检查"，subagent 处理"读操作的 context 隔离"，CLAUDE.md 处理"跨会话状态持久化"。为了配合这套架构落地，数仓的研发流程可以拆解为 8 个大的步骤，流程图如下：

从 Harness 架构的视角来看，8 个步骤可以按"对 context 的影响"分成两类：一类是直接在主会话处理 （内容量有限，context 压力低）：需求分析（读 PRD）、技术设计（写规范说明）、SR 导入（生成配置）、SLA/DQC（生成规则）。另一类必须通过 Harness 机制处理（否则会加速 compact 或规范失控）：ETL 开发每次写 .sql 文件，PostToolUse hook 自动触发规范检查，不依赖人工提醒；自测时 23 条 SQL 的执行结果体量大，交给 data-quality-checker subagent 隔离，主会话只收 PASS/FAIL 摘要；数据比对时两表样本数据量大，交给 data-comparator subagent 隔离；性能优化时血缘 + 多层 DDL 每次 500~3000 tokens，交给 dw-explorer subagent 隔离。这种分工不是把步骤拆开独立执行，而是在同一个工作流里，让每个步骤以最合适的方式运行------context 压力小的步骤留在主会话保持流畅，context 压力大的步骤通过 subagent 隔离保持干净，规范检查通过 hook 自动执行不需要人工干预。

六、基于 SKILL 规范的数仓工作流设计

数仓 8 步 SKILL 规范（需求分析→技术设计→ETL→自测→数据比对→SR 导入→性能优化→SLA/DQC）天然对应 Harness 的三层机制。核心思路是：SKILL 文件不变，改变调用方式------主对话只读规范结论，实际执行由 subagent 或 hook 完成。

各步骤推荐提示词与工作流

Step 1：需求分析

推荐提示词：

用 dw-explorer subagent 先读取上游表结构（只返回摘要），
然后按需求分析规范生成：
1. 需求摘要（≤5行）
2. 表字段口径草稿
3. 待确认问题清单（按优先级排序）
需求文档 URL：[粘贴PRD链接]

Hook 配合：SessionStart 注入当前迭代约束（版本号/表名/禁止修改的表）。

Step 2：技术设计

推荐提示词：

基于上一步确认的需求，按 OneData 规范完成技术设计：
 表名：[按 层级_域_主题_粒度_周期 格式命名]
 粒度：[描述]
 分区：partition_dt string（格式 yyyyMMdd）
 禁止：任何与上游不一致的字段命名
输出 OneData 建模说明，不超过 60 行

CLAUDE.md 写入（设计完成后手动更新）：

## 当前迭代技术设计决策- 表名：db_a.dws_table_a
- 主键：order_no + partition_dt
- 特殊约束：amount 字段继承上游千元单位，不做转换

Step 3：ETL 开发

这是 Harness 工程价值最高的步骤，PostToolUse hook 在每次 SQL 文件保存时自动触发。

推荐提示词：

按 ETL 开发规范生成建表 DDL + Insert SQL：
- 建表文件：ddl_[表名].sql
- 插入文件：insert_[表名].sql
- 要求：INSERT 用 OVERWRITE 模式，PARTITION 子句必须包含 partition_dt
- 金额字段：DECIMAL(20,4)，单位继承上游（千元）
生成完毕后，用 sql-validator subagent 验证两个文件

Hook 自动执行（无需手动触发）：每次写入 .sql 文件 → PostToolUse hook 自动运行规范检查。若发现 SELECT * 或缺少 PARTITION → 返回 exit 2，Claude 收到错误自动修正。

Step 4：自测

推荐提示词（防止自测结果撑爆主 context）：

用 data-quality-checker subagent 对 [表名] 执行 23 项标准自测，
bizdate = [日期]
补充口径约束：[如"is_perform=1 只取履约订单"]
只返回：PASS/FAIL 汇总 + FAIL 项详情（≤50行），不返回原始 SQL 执行结果

效果：23 条 SQL 的执行结果全在 subagent context 里，主对话只收到一份摘要报告。

Step 5：数据比对

推荐提示词：

用 data-comparator subagent 对比：
 新表：[新表名] partition_dt = [日期]
 参考表：[旧表名/线上表]
 比对字段：[核心金额字段列表]
 容差：≤ 0.01%（金额类）
只返回：差异超过容差的字段列表 + 差值，不返回全量对比数据

Step 6：SR数据库导入

推荐提示词（自动生成最优数据库建表参数）：

用 dw-sr SKILL生成建表任务， 先查以下表的 DDL 和一层上下游血缘（只返回摘要）：
- 源表：[ODPS表名]
- 目标表：[SR表名]

然后基于 DDL 摘要，分析当前 SR 同步任务的配置风险：
1. 字段类型是否有精度丢失风险（DECIMAL/DOUBLE → DECIMAL(38,18)）
2. Key 字段选择是否合理（重复率是否过高导致 DUPLICATE KEY 膨胀）
3. 分区数量是否合理（partition_live_number 与下游查询窗口是否匹配）
4. DISTRIBUTED BY HASH 的 bucket 数与数据量是否匹配
5. 是否有 DATETIME 字段在 SR 侧用了 VARCHAR 存储（会导致时间过滤走全表扫描）

输出同步任务配置建议（按风险高低排序），不超过 20 行。
每条格式：[风险等级 高/中/低] 问题描述 → 建议修改方式

Step 7：性能优化

推荐提示词（防止血缘查询撑爆主 context）：

用 dw-explorer subagent 先查 [表名] 的一层上下游血缘和 DDL（只返回摘要），
然后分析当前 Insert SQL 的性能瓶颈：
1. 是否有全表扫描
2. 是否有笛卡尔积风险
3. 是否可以用 MAP JOIN 替代 HASH JOIN
输出优化建议（按收益排序），不超过 30 行

Step 8：SLA/DQC

推荐提示词：

按 SLA/DQC 规范为 [表名] 生成 9 类 DQC 规则：
 完整性：主键非空、分区数据量
 准确性：核心金额字段与上游比对（容差 0.01%）
 一致性：is_perform 与 perform_flag 联动逻辑
 时效性：产出时间 SLA ≤ 次日 8:00
输出 DQC 配置 JSON，可直接使用

SKILL 调用方式改造（减少主 context 消耗）

当前问题：触发 SKILL 时，SKILL 文件全文（约 10KB）加载进主 context，加速 compact。改造方向：

核心原则：主对话只接收决策级信息（PASS/FAIL、差异字段、优化方案），不接收过程数据（SQL 执行结果、原始血缘列表、完整 DDL 内容）。

精准对话流设计：控制AI思考的艺术

文章中多次提到 /dw-etl、/dw-自测等命令，这是数仓研发全流程 SKILL 套件的核心触发词，每个命令对应一个封装了规范、产出格式和工具调用的标准化执行单元。核心理念：把每次都要重复讲的要求写进 SKILL，把每次都怕忘的检查点写进 SKILL，把每次都需要的结构化输出也写进 SKILL------这样谁来做需求都行，底座是一致的。

8 个 SKILL 命令一览

以 /dw-etl 为例：一条命令封装了什么？ETL 开发（Step 3）是 Harness 工程价值最高的步骤，SKILL 文件内封装了：① 规范内容（写死，不靠记忆）：建表规范：分区字段必须是 partition_dt STRING（格式 YYYYMMDD）；金额字段：DECIMAL(26,4)，不用 DOUBLE；INSERT 模式：必须使用 INSERT OVERWRITE，必须带 PARTITION 子句；禁止：SELECT *、跨库 JOIN（非血缘关系）。② 产出格式（结构化，不走样）：

输出文件：
├── ddl_[表名].sql      ← ODPS 建表语句（含注释三段式、生命周期配置）
├── insert_[表名].sql   ← ODPS Insert SQL（含分区裁剪、JOIN 规范）
└── ddl_sr_[表名].sql   ← SR 建表语句（Key 列顺序、DECIMAL 精度）

③ 自动护栏（Hook 配合）：每次 .sql 文件写入后，PostToolUse hook 自动执行 validate_sql.sh；发现 SELECT * 或缺少 PARTITION → exit 2 阻断，Claude 强制修正。④ subagent 卸载（防 context 膨胀）："生成完毕后，用 sql-validator subagent 验证两个文件"；验证结果全在 subagent context 里，主对话只收到"PASS/FAIL + 问题列表"。综合效益数据：

七、落地步骤

步骤一：项目级上下文持久化。在数仓项目目录下创建 .claude/CLAUDE.md，写入当前迭代状态。每次新迭代开始时更新"正在开发"和"本次迭代约束"两节，上线后清空约束节。全局规范永久保留，控制在 100 行以内。

步骤二：配置 hooks 自动验证。创建 .claude/settings.json + hooks/ 目录，配置 PostToolUse hook（每次写 .sql 后自动规范检查）和 PreToolUse hook（拦截危险 DDL）。效果：不需要每次手动说"帮我检查 SQL 规范"，hook 在 Harness 层自动触发，不占用 Claude 推理资源。

步骤三：创建 subagents 隔离高 token 操作。创建三个核心 subagent 文件：sql-validator.md、dw-explorer.md、data-quality-checker.md。将 Step 4/5/7 的执行全部下放，预计主 context compact 频率降低 50%~70%。

八、Harness 工程能解决的核心问题

这一节是整个方案的出发点，也是对"为什么要这么做"的直接回答。

数仓 AI 开发当前的本质瓶颈：语义理解

在实际数仓 AI 开发中，技术能力不是瓶颈，语义理解才是。需求理解偏差占总返工的 40%～60%，大约 40%～50% 的工作时间花在理解需求和与业务核对口径上。精准血缘探查：准确率提升显著，远超传统方式。这两个观察揭示了同一个问题：AI 在数仓场景的不准确，根本原因不是"不会写 SQL"，而是"不理解业务语义"------不知道这张表的 amount 单位是千元还是元，不知道 is_perform=1 在这个版本里意味着什么，不知道某字段在特定场景下会为空。

语义 × 数据 = 准确率

数仓 AI 开发的准确率，可以用一个公式来理解：

准确率 = 语义理解深度 × 数据规范覆盖度

结论：Harness 工程的本质，是把"语义"和"规范"从不可靠的 LLM 记忆中，迁移到确定性的 hooks + 持久化文件里，从而让语义 × 规范 = 准确率这个等式两边的变量都变得稳定。

具体能解决的四类问题

问题一：字段口径遗忘导致的计算错误

现状：对话开始时告知了"amount 字段单位是千元"，compact 后 Claude 忘了，生成的 SQL 把千元当元用，导致数据差 1000 倍。Harness 解法：字段口径写进 .claude/CLAUDE.md（compact 后重新注入）；踩坑经验写进 Auto Memory（跨会话持久化）；结果：这类错误从"时常发生"降到"基本不出现"。

问题二：需求理解偏差导致的返工

现状：需求文档描述的是"用户视角的 GMV"，但 AI 生成了"交易视角的 GMV"，两者口径不同，数据对不上，需要返工。Harness 解法：需求分析的产出（口径草稿 + 待确认问题清单）写进 CLAUDE.md 的迭代约束节；Stop hook 检查任务完整性，确认待确认问题清单已全部明确后才放行；结果：需求一次交付通过率从约 50% 提升到 90%。

问题三：SQL 规范执行不一致

现状：规范文档写了"INSERT 必须带 PARTITION"，但 Claude 有时会忘，或在 compact 后规范内容被清除后生成不合规的 SQL。Harness 解法：PostToolUse hook 在每次写 .sql 文件后自动执行规范检查，不依赖 Claude 记忆；违规时 exit 2 返回错误，Claude 强制修正后才能继续；结果：规范执行率从"依赖 LLM 记忆的 70%~80%"提升到"hook 强制的 95%+"。

问题四：大型需求开发中的 context 耗尽

现状：复杂需求（大型宽表、大量下游血缘）开发过程中，血缘查询 + 自测结果 + SKILL 文件内容堆满 context，compact 触发后丢失关键约束，Claude 开始犯低级错误。Harness 解法：血缘查询 → dw-explorer subagent（独立 context，只返回摘要）；23 项自测 → data-quality-checker subagent（独立 context，只返回 PASS/FAIL 报告）；SKILL 文件内容 → subagent 内部读取，主 context 只接收产出的 SQL 文件路径；结果：主 context compact 频率预计降低 50%~70%。

与传统数仓 AI 开发方式的对比

从"AI 帮我写代码"到"AI 嵌入研发流水线"

Harness 工程的最终目标，不是让 Claude 更聪明，而是让整个研发流水线更可靠。Claude（LLM）负责：理解需求、设计方案、生成代码------这些需要语义理解的事；Harness（hooks）负责：规范检查、危险拦截、任务完整性验证------这些需要确定性执行的事；Subagents 负责：大量文件读取、血缘查询、自测执行------这些会消耗大量 context 的事；CLAUDE.md + Memory 负责：字段口径、迭代约束、踩坑经验------这些需要跨会话持久化的事。这四层分工，让数仓 AI 开发从"对话驱动的一次性辅助"升级为"规则嵌入的流水线自动化"。

往期回顾

1.[BP Claw 破解 AI 编码输入难题 ------FlinkSpec 需求智能化实践｜得物技术](# 一、AI Coding 现状与痛点：为什么需要 Harness

当前使用情况

得物离线数仓各小组已基本完成 AI Coding 工具的覆盖，主力工具为 Claude Code，辅以数据平台的 IDE 插件，应对重复性工作时效率提升明显。

核心痛点

尽管整体提效已显现，但团队在实际使用中暴露出三类结构性痛点。

痛点三：大型需求开发中，context 很快被撑满，越到后期 AI 越不可靠。复杂需求（大型宽表、大量下游血缘）的典型开发过程：

血缘查询结果（500~3000 tokens） 自测 23 条 SQL 执行结果（5000~15000 tokens） SKILL 规范文件内容（~10000 tokens） 数据比对两表样本（大量行）= context 迅速膨胀 → compact 触发 → 关键约束遗忘 → AI 开始犯低级错误

核心矛盾：越是复杂的需求，越依赖 AI；但越复杂的需求，context 越容易撑满，AI 越容易"失忆"。

从"随手问 AI"到"把能力封装起来"

二、先搞清楚"Harness"是什么

在 Claude Code 的 update-config skill 描述中有一句话："Automated behaviors require hooks configured in settings.json --- the harness executes these, not Claude"。

三、核心问题：compact 到底丢掉什么？

四、五层防御体系（从简单到复杂）

第一层：写死进 CLAUDE.md（立即可用）

机制：项目根目录 .claude/CLAUDE.md 每次 compact 后从磁盘重新注入，是最可靠的持久化位置。将当前迭代的关键信息写入，格式建议：

# 当前迭代状态（每次迭代手动更新）## 正在开发- 表：db_a.dws_table_a
 版本：V1.0
 node_id：1000000001
 状态：ETL开发阶段（Step 3/8）

## 本次迭代约束- 禁止修改：dwd_table_b（已上线，只读）
 分区字段：partition_dt（格式 yyyyMMdd，不是 dt）
 amount 字段单位：千元（不是元）

## 数仓全局规范
 建表：分区字段必须是 partition_dt string
 禁止：SELECT *，UPDATE/DELETE 无 WHERE
 金额字段用 DECIMAL(20,4)，不用 DOUBLE
 INSERT 必须带 PARTITION 子句

操作规则：进入新迭代时，更新"正在开发"和"本次迭代约束"两节；上线后清空"本次迭代约束"；全局规范长期保留，控制在 100 行以内。

第二层：Auto Memory 自动积累（已在运行）

第三层：hooks 自动验证（核心防御，解决"忘了检查"的问题）

这是解决"每次写完 SQL 自动检查"的关键机制。

配置文件位置

数仓项目根目录/
└── .claude/
    ├── settings.json          ← hooks 在这里配置
    ├── CLAUDE.md              ← 数仓规范上下文
    └── hooks/
        ├── validate_sql.sh          ← SQL 规范自动检查
        ├── block_dangerous_ddl.sh   ← 危险 DDL 拦截
        └── inject_context.sh        ← compact 后重注入上下文

settings.json 完整配置

{"hooks": {"PostToolUse": [{"matcher": "Write|Edit","hooks": [{"type": "command","command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/validate_sql.sh","timeout": 60,"statusMessage": "检查 SQL 规范..."}]}],"PreToolUse": [{"matcher": "Bash","hooks": [{"type": "command","command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block_dangerous_ddl.sh"}]}],"SessionStart": [{"matcher": "compact","hooks": [{"type": "command","command": "cat \"$CLAUDE_PROJECT_DIR\"/.claude/context/dw_conventions.md","statusMessage": "重注入数仓规范..."}]}],"Stop": [{"hooks": [{"type": "prompt","prompt": "检查用户要求的所有任务是否都已完成。如果还有未完成项，返回提示但不要重新开始。检查 stop_hook_active 是否为 true，如是则直接 exit。","model": "claude-haiku-4-5-20251001"}]}]}}

SQL 规范自动检查脚本

.claude/hooks/validate_sql.sh：

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo"$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_input',{}).get('file_path',''))" 2>/dev/null)

# 只处理 .sql 文件
[[ "$FILE_PATH" != *.sql ]] && exit 0
[[ -z "$FILE_PATH" ]] && exit 0

SQL=$(cat "$FILE_PATH" 2>/dev/null)
[[ -z "$SQL" ]] && exit 0

ERRORS=()

# 规范1：禁止 SELECT *echo "$SQL" | grep -iqE 'SELECT\s+\*' && ERRORS+=("CRITICAL: 发现 SELECT *，必须明确列名")

# 规范2：INSERT 必须带 PARTITIONif echo "$SQL" | grep -iqE 'INSERT\s+(INTO|OVERWRITE)'; thenecho "$SQL" | grep -iqE 'PARTITION\s*\(' || ERRORS+=("CRITICAL: INSERT 缺少 PARTITION 子句")
fi# 规范3：DOUBLE 类型金额echo "$SQL" | grep -iqE '\bDOUBLE\b' && ERRORS+=("WARNING: 金额字段建议用 DECIMAL(20,4)，不用 DOUBLE")

# 规范4：UPDATE/DELETE 必须有 WHEREif echo "$SQL" | grep -iqE '\b(UPDATE|DELETE)\b'; thenecho "$SQL" | grep -iqE '\bWHERE\b' || ERRORS+=("CRITICAL: UPDATE/DELETE 缺少 WHERE 条件")
fiif [ ${#ERRORS[@]} -gt 0 ]; thenecho "=== SQL 规范检查失败：$FILE_PATH ===" >&2
  for err in"${ERRORS[@]}"; doecho "  $err" >&2
  doneexit 2
fiecho "SQL 规范检查通过: $(basename $FILE_PATH)" >&2
exit 0

危险 DDL 拦截脚本

.claude/hooks/block_dangerous_ddl.sh：

#!/bin/bash
INPUT=$(cat)
CMD=$(echo"$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_input',{}).get('command',''))" 2>/dev/null)

# 拦截生产表 DROP/TRUNCATE（放行 _dev/_test/_stg 后缀）if echo "$CMD" | grep -iqE '\b(DROP\s+TABLE|TRUNCATE\s+TABLE)\b'; thenif ! echo "$CMD" | grep -qiE '(_dev|_test|_stg)\b'; thenecho "BLOCKED: 检测到生产表 DROP/TRUNCATE 操作，请确认表名是否正确" >&2
    exit 2
  fifiexit 0

hook 通信协议关键规则

关键陷阱：阻断必须用 exit 2，用 exit 1 不会阻止 Claude 继续执行。

第四层：subagents 做上下文隔离（防 context 膨胀）

核心原则：把"高 token 消耗但结果只需要摘要"的操作放到 subagent 的独立 context 中执行。

数仓场景适合下放 subagent 的操作

创建 subagent 文件

.claude/agents/sql-validator.md（SQL 语法验证）：

---
name: sql-validator
description: ODPS/MaxCompute SQL 语法验证与规范检查专用 agent。当用户生成或修改 SQL 文件后需要验证时调用。在独立 context 运行，防止大量验证日志污染主对话。
tools: Read, Bash, Grep, Glob
model: haiku
permissionMode: dontAsk
---

你是数仓 SQL 规范专家，只做验证，不修改文件。

验证项（按优先级）：
1. SELECT * 禁止
2. INSERT 必须带 PARTITION
3. 字段用 snake_case 命名
4. 金额字段用 DECIMAL 不用 DOUBLE
5. 多表 JOIN 必须有 ON 条件
6. 笛卡尔积风险检测

输出格式：
- 状态：PASS / FAIL
- 问题列表（CRITICAL / WARNING / INFO）
- 修改建议（具体到行号）

不超过 50 行，只返回结构化报告。

.claude/agents/dw-explorer.md（防止血缘查询撑爆主 context）：

---
name: dw-explorer
description: 数仓结构探索 agent。当需要大量读取表结构、DDL、字段信息、血缘关系时自动调用，避免大量文件内容污染主 context。只读，不修改任何文件。
tools: Read, Glob, Grep, Bash
model: haiku
permissionMode: dontAsk
---

你是数仓探索专家，只读操作。

当被调用时：
1. 读取指定表的 DDL、字段信息、分区策略
2. 分析上下游血缘（一层）
3. 识别关键字段口径（金额、日期、状态类字段）

输出：不超过 80 行的结构化摘要，包含：
- 表基本信息（层级、粒度、分区策略）
- 核心字段定义（含口径说明）
- 上下游血缘（只列表名，不展开内容）
- 发现的特殊口径或踩坑点

使用方式

在主对话中自然触发：

用 dw-explorer 分析 db_a.dwd_table_a 的结构

对刚生成的 insert_dws_table_a.sql 用 sql-validator 验证

或强制指定（避免 Claude 自行判断）：

@"sql-validator (agent)" 验证 path/to/insert.sql

第五层：SKILL 文件改造（减少 context 消耗）

---
# .claude/rules/etl-rules.md
paths:
  - "**/*insert*.sql"
  - "**/*_di.sql"
  - "**/*_df.sql"
---

# ETL 开发规范（按文件路径自动加载）
- 必须有 partition_dt 分区
- INSERT OVERWRITE 前检查分区是否已存在
- 不允许跨库 JOIN

五、可行落地方案：数仓 Harness 架构

先让我们看一下整体的架构设计（整体架构图）：

这张架构图的核心逻辑是职责分层：不同类型的工作交给最合适的机制去做，而不是全部压在 Claude 的推理循环里。

六、基于 SKILL 规范的数仓工作流设计

各步骤推荐提示词与工作流

Step 1：需求分析

推荐提示词：

用 dw-explorer subagent 先读取上游表结构（只返回摘要），
然后按需求分析规范生成：
1. 需求摘要（≤5行）
2. 表字段口径草稿
3. 待确认问题清单（按优先级排序）
需求文档 URL：[粘贴PRD链接]

Hook 配合：SessionStart 注入当前迭代约束（版本号/表名/禁止修改的表）。

Step 2：技术设计

推荐提示词：

基于上一步确认的需求，按 OneData 规范完成技术设计：
 表名：[按 层级_域_主题_粒度_周期 格式命名]
 粒度：[描述]
 分区：partition_dt string（格式 yyyyMMdd）
 禁止：任何与上游不一致的字段命名
输出 OneData 建模说明，不超过 60 行

CLAUDE.md 写入（设计完成后手动更新）：

## 当前迭代技术设计决策- 表名：db_a.dws_table_a
- 主键：order_no + partition_dt
- 特殊约束：amount 字段继承上游千元单位，不做转换

Step 3：ETL 开发

这是 Harness 工程价值最高的步骤，PostToolUse hook 在每次 SQL 文件保存时自动触发。

推荐提示词：

按 ETL 开发规范生成建表 DDL + Insert SQL：
- 建表文件：ddl_[表名].sql
- 插入文件：insert_[表名].sql
- 要求：INSERT 用 OVERWRITE 模式，PARTITION 子句必须包含 partition_dt
- 金额字段：DECIMAL(20,4)，单位继承上游（千元）
生成完毕后，用 sql-validator subagent 验证两个文件

Step 4：自测

推荐提示词（防止自测结果撑爆主 context）：

用 data-quality-checker subagent 对 [表名] 执行 23 项标准自测，
bizdate = [日期]
补充口径约束：[如"is_perform=1 只取履约订单"]
只返回：PASS/FAIL 汇总 + FAIL 项详情（≤50行），不返回原始 SQL 执行结果

效果：23 条 SQL 的执行结果全在 subagent context 里，主对话只收到一份摘要报告。

Step 5：数据比对

推荐提示词：

用 data-comparator subagent 对比：
 新表：[新表名] partition_dt = [日期]
 参考表：[旧表名/线上表]
 比对字段：[核心金额字段列表]
 容差：≤ 0.01%（金额类）
只返回：差异超过容差的字段列表 + 差值，不返回全量对比数据

Step 6：SR数据库导入

推荐提示词（自动生成最优数据库建表参数）：

用 dw-sr SKILL生成建表任务， 先查以下表的 DDL 和一层上下游血缘（只返回摘要）：
- 源表：[ODPS表名]
- 目标表：[SR表名]

然后基于 DDL 摘要，分析当前 SR 同步任务的配置风险：
1. 字段类型是否有精度丢失风险（DECIMAL/DOUBLE → DECIMAL(38,18)）
2. Key 字段选择是否合理（重复率是否过高导致 DUPLICATE KEY 膨胀）
3. 分区数量是否合理（partition_live_number 与下游查询窗口是否匹配）
4. DISTRIBUTED BY HASH 的 bucket 数与数据量是否匹配
5. 是否有 DATETIME 字段在 SR 侧用了 VARCHAR 存储（会导致时间过滤走全表扫描）

输出同步任务配置建议（按风险高低排序），不超过 20 行。
每条格式：[风险等级 高/中/低] 问题描述 → 建议修改方式

Step 7：性能优化

推荐提示词（防止血缘查询撑爆主 context）：

用 dw-explorer subagent 先查 [表名] 的一层上下游血缘和 DDL（只返回摘要），
然后分析当前 Insert SQL 的性能瓶颈：
1. 是否有全表扫描
2. 是否有笛卡尔积风险
3. 是否可以用 MAP JOIN 替代 HASH JOIN
输出优化建议（按收益排序），不超过 30 行

Step 8：SLA/DQC

推荐提示词：

按 SLA/DQC 规范为 [表名] 生成 9 类 DQC 规则：
 完整性：主键非空、分区数据量
 准确性：核心金额字段与上游比对（容差 0.01%）
 一致性：is_perform 与 perform_flag 联动逻辑
 时效性：产出时间 SLA ≤ 次日 8:00
输出 DQC 配置 JSON，可直接使用

SKILL 调用方式改造（减少主 context 消耗）

当前问题：触发 SKILL 时，SKILL 文件全文（约 10KB）加载进主 context，加速 compact。改造方向：

核心原则：主对话只接收决策级信息（PASS/FAIL、差异字段、优化方案），不接收过程数据（SQL 执行结果、原始血缘列表、完整 DDL 内容）。

精准对话流设计：控制AI思考的艺术

8 个 SKILL 命令一览

输出文件：
├── ddl_[表名].sql      ← ODPS 建表语句（含注释三段式、生命周期配置）
├── insert_[表名].sql   ← ODPS Insert SQL（含分区裁剪、JOIN 规范）
└── ddl_sr_[表名].sql   ← SR 建表语句（Key 列顺序、DECIMAL 精度）

七、落地步骤

八、Harness 工程能解决的核心问题

这一节是整个方案的出发点，也是对"为什么要这么做"的直接回答。

数仓 AI 开发当前的本质瓶颈：语义理解

语义 × 数据 = 准确率

数仓 AI 开发的准确率，可以用一个公式来理解：

准确率 = 语义理解深度 × 数据规范覆盖度

具体能解决的四类问题

问题一：字段口径遗忘导致的计算错误

问题二：需求理解偏差导致的返工

问题三：SQL 规范执行不一致

问题四：大型需求开发中的 context 耗尽

与传统数仓 AI 开发方式的对比

从"AI 帮我写代码"到"AI 嵌入研发流水线"

往期回顾

1.BP Claw 破解 AI 编码输入难题 ------FlinkSpec 需求智能化实践｜得物技术

2.基于 Harness + SDD + 多仓管理模式的 AI 全栈开发实践｜得物技术

3.通用 AI Agent 驱动网关路由安全审计实践｜得物技术

4.AI驱动：从运营行为到自动化用例的智能化实践｜得物技术

5.生成式召回在得物的落地技术分享与思考

文 /丹克

关注得物技术，每周更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。 )

2.基于 Harness + SDD + 多仓管理模式的 AI 全栈开发实践｜得物技术

3.通用 AI Agent 驱动网关路由安全审计实践｜得物技术

4.AI驱动：从运营行为到自动化用例的智能化实践｜得物技术

5.生成式召回在得物的落地技术分享与思考

文 /丹克

关注得物技术，每周更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。

Flutter 3.44 发布啦，超级大版本更新！！！

恋猫de小郭 — Thu, 21 May 2026 01:05:30 GMT

虽然 Flutter 3.44 的版本已经发布两天了，但是今天才是真正的官宣 Flutter 3.44 发布哦，3.44 虽然看起来版本号不大，但是这确实是一个超级大版本更新。

也不知道为什么 Flutter 对于 3.x 这个版本号这么热爱，就和 RN 热爱 0.x 一样。

这次 3.44 核心包括 Android HC++ 功能落地、iOS/MacOS 默认使用 Swift PM、多窗口功能落地、Material 和 Cupertino 解耦、各种 AI 场景支持、Widget Previewer 更新和各种功能优化。

首先还是按照惯例，Flutter 先公布了近期的一些数据情况，其中 pub.dev 在过去 30 天内， Package 下载量超过 13 亿次，Flutter 两大应用商店下月活开发者超过 150 万，一年内增长了 50%。

这算是惯例对于「Flutter 凉了没」的回覆。

工具更新

Widget Previewer

虽然我基本没怎么用过，但是 Flutter 官方一直很热衷 Widget Previewer 的优化，这次主要有两个内容：

预览检测的逻辑重写了，使用 analysis server 做 widget preview detection，降低了 Flutter 工具的内存占用，对于 IDE 用户而言，整体内存占用最多可降低 50%
自定义 preview annotation 支持 collections 和 records，现在可以按组、名称、脚本和包 URI 筛选预览

3.44 的 Previewer 其实就是接入了更底层的 analysis server 检测链路，主要涉及：

IDE 能准确知道哪些函数、构造器、静态方法可以 preview
Previewer 要能处理真实项目里的 wrapper、theme、localization、状态注入
依赖真实 analyzer 级别的语义信息

可以看出来官方对于 Widget Previewer 很重视，大概在 AI 时代，Widget Previewer 可以在开发过程中，有不错的事实预览效果。

不需要 Rosetta

这个我们提前聊过，在之前的《Flutter iOS 又修复了一个构建问题》就提到过，以前 Flutter 本身的构建工具还是需要 Rosetta 进行适配支持，这次所有的 macOS 命令行工具都已经通过 Fat Binary，从而同时支持 x86_64 和 arm64 两种架构。

因为下个版本 Rosetta 就要开始推出历史舞台了，所以这也算事一个重要的跟进升级，当然，这个能力的 PR 的过程很抽象，没看过的可以了解下，是真的草台。。。。

AI

Flutter 官方真的很热衷跟进各种 AI 能力，而且跟进的贼快。

Agentic Hot Reload

3.44 官方推出了全新的 Agentic Hot Reload 功能，Flutter 在 AI 支持能力上一直很热衷，这次的 Agentic Hot Reload 也是。

从 3.44 开始，一些 MCP 服务器和 Coding Agnet 支持自动查找并连接到正在运行的 Flutter App ，也就是类似 Antigravity 这样的 Coding Agnet 可以支持使用 Hot Reload，同时还有配置前面的 Previewer ，整体 AI 开发体验会更好。

另外，Agent 现在可以通过服务，直接读取本地 pub 包依赖，不需要去取搜索本地 pub 缓存，同时 MCP 相关的 Tools 也得到了更新。

实际上这个能力以前也能做到，AI 通过命令行的 r 输入也可以，但是这次的是让 agent 有官方路径去发现运行中的 Flutter session，agent 可以知道是哪个 App 正在运行，因为是一整套的 MCP 协议支持。

Skills

关于 skills 在不久前我们也刚聊过，《新 Flutter & Dart Agent Skills 深度解读》，现在官方的 skills 都是**“任务导向型”的 Skills**，每个 Skill 都不是在描述一个功能或者说明一个文档，而是在提供一套决策逻辑，让 AI 可以通过明确指令来解决问题，并且提供对应的反馈循环（Feedback Loop）。

每个技 Skill 的结果都需要做检验，类似 flutter-fix-layout-issues、flutter-add-widget-test 、flutter-add-integration-test 、flutter-build-responsive-layout、flutter-setup-localization 、flutter-implement-json-serialization 、flutter-add-widget-preview 、dart-fix-runtime-errors 、dart-use-pattern-matching 都是很实用的技能。

Genkit Dart

关于 GenKit 我们之前也一样在《谷歌 Genkit Dart 正式发布》聊过，基于Genkit 可以构建全栈式 AI 驱动的智能体应用：

Flutter 使用 Dart 可以直接原生实现 AI 编排框架，支持不同模型和本地场景，提供 agent workflow / tool calling / RAG 等能力 。

通过 Genkit Dart 你可以实现一整套的 Agent 的服务端和客户端能力，支持 Google、Anthropic 、 OpenAI 甚至本地模型的能力，包括类型安全的结构化输出、工具调用、多轮对话和内置的可观测性能力等等。

import 'package:genkit/genkit.dart';
import 'package:genkit_google_genai/genkit_google_genai.dart';

void main() async {
 final ai = Genkit(plugins: [googleAI()]);

 final response = await ai.generate(
   model: googleAI.gemini('gemini-flash-latest'),
   prompt: 'Why is Dart a great language for AI
            applications?',
 );

 print(response.text);
}

Gemma 4

Flutter 也支持直接跑 Gemma 4 本地模型，通过 flutter_gemma 插件，App 可以和 Gemma 深度集成，插件底层支持 LiteRT-LM ，支持 GPU 和 NPU 加速，最重要是支持全平台：

GenUI

这个大家应该也不陌生吧，我们在《Flutter GenUI 0.9 和 A2UI 0.9 发布》才刚刚聊过，官方表示：Flutter + A2UI = GenUI

作为基于 AI 的生成式 UI 支持，Flutter 算是在 A2UI 领域最早的支持项目之一，它提供了一套完整的协议实现，可以让 Agent 在 App 运行中动态生成控件，客户端不需要开发一个完整的页面功能，开发者只需要维护组建库，剩下的都交给 AI 。

官方统计，自从推出 Flutter GenUI SDK 以来，软件包下载量自年初以来增长了 500%。

官方特别提到了 Catagay Ulusoy 开发的 Finnish it （可在 Google Play 商店和 Apple Store 下载）例子，这款应用不仅能为用户创建定制化的课程计划来学习芬兰语，还能根据每节课的需要动态生成完美的界面：

另外还有官方提供的 Demo ，也分享了 DeepMind 使用 Flutter 构建 Gemini App “可视化布局”的效果：

Android

首先就是 Googlebook 支持，我都还没用上，Flutter 就宣布了 Googlebook 已经适配完成，核心是适配了 Gemini 处理器的全新 Googlebook 笔记本电脑，不过具体支持的如何，还需要看真的发布后才知道。

另外还有 Android 17 的适配， Flutter 3.44 也正在完成 Android 17 的适配，包括本地网络保护和安全动态代码加载等场景。

Hybrid Composition++

另外还有一个重点就是 Hybrid Composition++ 终于落地了，这个我们再去年的《Flutter 正在推进全新 PlatformView 实现 HCPP》就提到过，这是一套全新的 PlatformView 实现，可以提供更好的 PlatformView 新能：

HCPP 不再依赖屏幕外缓冲区或强制 Flutter 引擎处理原生视图，而是将图层合成直接委托给 Android 本地，然后利用 Vulkan 图形库的底层访问能力，通过硬件缓冲区交换链和 SurfaceControl 事务将 Flutter UI 与原生 Android 视图同步。

简单来说就是，HCPP 主要就是通过 SurfaceControl 来构造一个高层级的 Surface 从而实现最终绘制时混合覆盖的问题，这和《深入 Flutter 和 Compose 的 PlatformView 实现对比》里 Compose 可以在 PlatformView 里直接使用 SurfaceView 的道理类似，都是 SurfaceFlinger 合成时的层级操作。

只是需要 Vulkan 和 API 34 的环境才支持使用 。

所以 HCPP 对 Android API 和硬件有一定要求，可以通过在 run 中添加 --enable-hcpp 或者在 AndroidManifest.xml 文件中添加相应的配置标志来启用：

<meta-data
  android:name="io.flutter.embedding.android.EnableHcpp"
    android:value="true" />

Android 显示屏圆角

Android 设备圆角支持，PredictiveBackPageTransitionsBuilder 新增对 MediaQuery.displayCornerRadiiOf(context) 的使用。

简单说，Android 设备真实屏幕圆角可以参与页面返回转场的裁剪效果，让转场更贴合物理设备边界。

如果你的应用自己覆盖了 Android 页面转场，可以显式使用这个 builder；设备圆角会由 MediaQuery.displayCornerRadiiOf(context) 自动参与裁剪，拿不到设备圆角时走 fallback：

MaterialApp(
  theme: ThemeData(
    pageTransitionsTheme: const PageTransitionsTheme(
      builders: <TargetPlatform, PageTransitionsBuilder>{
        TargetPlatform.android: PredictiveBackPageTransitionsBuilder(
          fallbackColor: Colors.black,
        ),
      },
    ),
  ),
  home: const HomePage(),
)

AGP 9 和 built-in Kotlin

在 AGP 9 版本之前，Android 应用和插件需要手动将 Kotlin Gradle 插件 (KGP) 添加到构建文件，系统才能识别并编译 Kotlin 代码。

从 AGP 9.0 开始，Android 构建系统已原生支持 Kotlin，由于构建系统已经处理了 Kotlin，手动添加单独的 KGP 会导致冲突并造成构建失败，所以这个情况需要 Flutter 进行适配，所以：

如果你是开发 Flutter App，这里需要更新 Android 构建文件，删除单独的 Kotlin Gradle 插件 (KGP)
如果是插件的话，就需要对 Gradle 进行修改兼容

设置 AGP 9.0 的插件必须 pubspec.yaml 里将 Flutter 的最低版本限制设置为 3.44 。

这个问题主要还是 AGP 和 Kotlin 的破坏性更新带来的，以前 Flutter Android 项目里常见的是：

plugins {
    id "com.android.application"
    id "kotlin-android"
}

或者老写法：

apply plugin: 'com.android.application'
apply plugin: 'kotlin-android'

而到了 AGP 9.0，Android Gradle Plugin 自己内置了 Kotlin 支持同时默认启用，也就是说普通 Android app/library 模块里不再需要显式 apply org.jetbrains.kotlin.android 或 kotlin-android 插件。

Google 官方说法是：AGP 9.0 introduces built-in Kotlin support and enables it by default，不再需要 apply org.jetbrains.kotlin.android / kotlin-android 来编译 Kotlin 源码。

所以迁移后的 Flutter Android app 大致会从：

plugins {
    id "com.android.application"
    id "kotlin-android"
    id "dev.flutter.flutter-gradle-plugin"
}

android {
    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_17.toString()
    }
}

变成：

plugins {
    id "com.android.application"
    id "dev.flutter.flutter-gradle-plugin"
}

android {
    // ...
}

kotlin {
    compilerOptions {
        jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
    }
}

也就是 删掉 kotlin-android，删掉 android { kotlinOptions {} }，改用顶层 kotlin { compilerOptions {} }。

Flutter 3.44 也不是强行让所有项目马上完全迁到 AGP 9 + built-in Kotlin，所以也加了两个 flag 做缓冲：

android.newDsl=false
android.builtInKotlin=false

而为了支持还没迁移的项目，Flutter 默认使用 legacy Kotlin Gradle Plugin 和 old AGP DSL types，Flutter migrator 会自动把这两个 flag 加到 gradle.properties。

ABI

Flutter 之前的做法是帮你按构建类型动态塞 ABI 过滤器，现在改成「在 defaultConfig 里统一塞一次」，这个变化也是遇到 AGP 9 的合并规则后。

以前一般是 flutter build apk --target-platform android-arm64 或者 flutter build apk --split-per-abi ，而现在为了 AGP9 ， Flutter 把 ABI filter 放到了 defaultConfig ：

android {
    defaultConfig {
        ndk {
            abiFilters ...
        }
    }
}

所以，如果在特定构建类型或产品风格中使用自定义 abiFilters ，现在需要在构建或运行应用时传递 -Pdisable-abi-filtering=true 标志。

iOS

Swift PM 默认

这个我们其实也已经在《Flutter 3.44 发布前夕，官方宣布 SwiftPM 将完全取代 CocoaPods》聊过，从 Flutter 3.44 开始，Swift Package Manager 成为是 iOS/macOS 的默认包管理器，同时这个包含了大量SwiftPM 的修复，例如：

CocoaPods 与 SwiftPM 冲突提示、SwiftPM 最低平台版本诊断、SwiftPM 下载太慢的慢提示、SwiftPM cache 集中化处理、SwiftPM Add-to-App 工具等。

现在 Flutter CLI 会自动处理迁移。构建或运行应用时，CLI 会将 Xcode 项目更新为使用 SwiftPM，如果依赖暂时不支持 SwiftPM，Flutter 会 fallback 到 CocoaPods，同时发出警告。

如果在 add-to-app 场景下，新的 flutter build swift-package 也会支持对应命令，如果 SwiftPM 是在无法兼容，页可以通过在 pubspec.yaml 文件中设置 --enable-swift-package-manager: false 来回退禁用。

UIScene

由于 Apple 已经强制了 UIScene 要求， 所以这里是想提醒你，如果还么迁移适配，那就要抓紧了。

predictive text

这是 iOS 上一个新的实验性支持，TextField、CupertinoTextField、EditableText 和 TextInputConfiguration 增加了 enableInlinePrediction 相关配置。

也就是 iOS 文本输入接入 inline prediction 提供了 opt-in 配置，并把配置从高层 TextField 传到底层 text input channel，Material 风格输入框可以这样显式打开：

TextField(
  controller: titleController,
  enableInlinePrediction: true,
  textInputAction: TextInputAction.done,
  decoration: const InputDecoration(
    labelText: '标题',
  ),
)

Cupertino 风格输入框也有同名参数：

CupertinoTextField(
  controller: titleController,
  enableInlinePrediction: true,
  placeholder: '标题',
  textInputAction: TextInputAction.done,
)

默认功能是关闭的，它目前只对 iOS 17 及以上的 inline predictive text 有用。

Web

这个版本主要都是一个简单优化，例如：

支持 prefers-reduced-motion ，也就是现在浏览器/系统说要“少动画”，Flutter Web 能够适配，然后 Web 还把这个偏好同步到 Flutter engine 的 accessibility 配置里，让 Flutter 侧的 disableAnimations / reduceMotion 生效。
另外现在 Flutter Web 表单错误能更快被屏幕阅读器读到，也算是无障碍的一个优化。
支持 iOS 26 Safari autofill ，Flutter Web 在 iOS 26 Safari 上不会再频繁销毁/重建用于 autofill 的隐藏 DOM form，而是尽量复用同一个 form，这样 Safari/密码管理器才能识别“这是一组连续的登录/注册表单字段”，从而正常自动填充。

Desktop

Flutter 这次不装了，直接宣布 Canonical 将成为 Flutter Desktop 的主要维护者和战略合作伙伴 ，这是什么意思？就是 Desktop 完全交给 Canonical 维护和主导了。

结果这次还是失望了， 虽然新增加了功能，但是多窗口功能还是只仅在 master 可以用，依然没有合并到 stable 。

这次多窗口新增加了 Tooltips 、Popups 和 Dialogs 的落地，同时 Linux 现在也支持了 content-sized 视图，可以根据窗口内容动态调整窗口大小。

另外这次更新里 showRawDialog / showDialog 可以走原生 dialog window ，如果通过 flutter config --enable-windowing 启用了 windowing，那么 dialog 会通过 windowing system 显示在自己的窗口中，而不是当前窗口内的 modal overlay，平台不支持时，会 fallback 到普通 dialog route。

其他还有 _window.dart 有了多类 controller 和 widget：

RegularWindowController / RegularWindow
DialogWindowController / DialogWindow
TooltipWindowController / TooltipWindow
PopupWindowController / PopupWindow
SatelliteWindowController / SatelliteWindow

嵌入式

这里官方主要介绍了一些案件，例如丰田的车机， RAV4 在 2025 年是全球最畅销的车型，而 2026 款 RAV4 正在使用 Flutter 构建车机系统 ：

LG 的基于 Flutter 的 WebOS SDK 页要更新发布了，webOS SDK 将包含对 Firebase、视频播放器、游戏手柄等插件的支持。

Impeller

3.44 版本包含多个 Vulkan 优化，包括「更好的缓存内存管理」，还有在丢帧情况下更高效的 GPU/CPU 同步，使用 SDF 可以实现更清晰的圆圈 ：

这个圈我看了是真头晕。

同时也改进了 Impeller 处理透视矩阵的方式，修正了阴影和透视投影变换的渲染行为，支持 Get Uniform by Name API ，可以在着色器中按名称绑定 uniform 变量：

    void setUp(ui.FragmentShader shader) {
      shader.getUniformFloat('foobar').set(1.234);
    }

Framework

解耦

3.44 开始，Material 和 Cupertino 就是独立的 material_ui 和 cupertino_ui 了，而下个版本发布的时候，框架内当前兼容的样式框就会被完全弃用兼容，整整 60 多万行代码的 PR ：

弹框

这次新增的 CupertinoMenuAnchor / CupertinoMenuItem 就是基于 widgets 层的 RawMenuAnchor 实现， Flutter 正在把“菜单锚点、打开/关闭、overlay、焦点和手势”这类共性逻辑放在更低层，让 Material 和 Cupertino 分别负责自己的视觉和交互风格。

3.44 新增 CupertinoMenuAnchor 和 CupertinoMenuItem，它们提供 Cupertino 风格的菜单 popup，支持 controller、open/close 回调、动画状态、overlay padding、长按打开、swipe 选择、focus/hover、destructive action 等能力：

CupertinoMenuAnchor(
  menuChildren: <Widget>[
    CupertinoMenuItem(
      leading: const Icon(CupertinoIcons.doc_on_doc),
      subtitle: const Text('创建一个副本'),
      trailing: const Icon(CupertinoIcons.right_chevron),
      onPressed: duplicateItem,
      child: const Text('复制'),
    ),
    const CupertinoMenuDivider(),
    CupertinoMenuItem(
      leading: const Icon(CupertinoIcons.delete),
      isDestructiveAction: true,
      onPressed: deleteItem,
      child: const Text('删除'),
    ),
  ],
  builder: (BuildContext context, MenuController controller, Widget? child) {
    return CupertinoButton(
      padding: EdgeInsets.zero,
      onPressed: () {
        controller.isOpen ? controller.close() : controller.open();
      },
      child: const Icon(CupertinoIcons.ellipsis_circle),
    );
  },
)

如果你不需要自己控制打开/关闭，也可以传 child 并配合外部 MenuController：

final MenuController controller = MenuController();

CupertinoMenuAnchor(
  controller: controller,
  menuChildren: <Widget>[
    CupertinoMenuItem(
      onPressed: () => controller.close(),
      child: const Text('完成'),
    ),
  ],
  child: CupertinoButton(
    onPressed: controller.open,
    child: const Text('更多'),
  ),
)

这里和 PlatformMenuBar 不一样：CupertinoMenuAnchor 是 Flutter 自己绘制的 Cupertino-style popup menu，适合控件附近的上下文菜单；PlatformMenuBar 则是交给宿主平台渲染的顶层菜单栏。

Material 的 MenuAnchor 也新增了 Material 3 动画， SubmenuButton 上的新 hoverOpenDelay 参数可以控制子菜单的交互，默认动画处于禁用状态，可以通过 animated 设置为 true 来启用：

另外， CupertinoSheetRoute 里面的可滚动内容现在可以和拖拽动画无缝协作，对于需要自定义拖拽区域的开发者来说，新的 scrollableBuilder 支持将托管的 ScrollController 传递给 body 的可滚动区域：

CarouselView 支持 infinite

CarouselView 这也也进行了大调整，最重要就是支持了 infinite：

Material CarouselView 新增 infinite 参数，开启后 Carousel 可以在两个方向连续循环滚动。

这个能力覆盖普通 CarouselView、CarouselView.weighted 和 lazy builder 场景，当 infinite 为 true 时，carousel 支持无限循环，双向连续滚动：

CarouselView(
  itemExtent: 280,
  infinite: true,
  children: List<Widget>.generate(6, (int index) {
    return Card.filled(
      child: Center(child: Text('推荐内容 $index')),
    );
  }),
)

SelectableRegion

不得不说，这个玩意一直都没完全支持好，这次 3.44 主要解决了两个问题：

Web 布局约束保留：之前 SelectableRegion 在网页上渲染时可能会导致对应子元素意外缩小，现在它会将所有布局约束原封不动地传递给子元素，从而确保一致的尺寸行为
多行复制精度，现在 SelectableRegion 中的文本选择更加精确，当用户选择并复制跨越多行的文本时，复制的输出中会正确保留换行符，不会丢失换行符

Superellipse

另外，Superellipse 现在覆盖更多 iOS 风格形状：

CupertinoFocusHalo.withRoundedSuperellipse 用 RoundedSuperellipseBorder 绘制更接近 iOS 的平滑圆角 focus halo
ShapedInputBorder 可一配合 RoundedSuperellipseBorder 做 iOS-style shape
Cupertino 的 dialog、context menu、sheet、list section、picker、segmented control 等路径已经基本采用 ClipRSuperellipse / RoundedSuperellipseBorder。

ClipRSuperellipse(
  borderRadius: BorderRadius.circular(28),
  child: Image.asset(
    'assets/cover.jpg',
    width: 160,
    height: 160,
    fit: BoxFit.cover,
  ),
)

ExpansionTile

最后， ExpansionTileController 页做了优化，作为 Material 组件 ExpansionTile 底层基础的 Expansible 组件， ExpansibleController 和 ExpansibleController 都新增了切换方法，Material 的列表图块 RadioListTile 、 CheckboxListTile 和 SwitchListTile 也支持了 WidgetStatesController 。

import 'package:flutter/material.dart';

class ExpansibleControllerDemo extends StatefulWidget {
  const ExpansibleControllerDemo({super.key});

  @override
  State<ExpansibleControllerDemo> createState() =>
      _ExpansibleControllerDemoState();
}

class _ExpansibleControllerDemoState extends State<ExpansibleControllerDemo> {
  final ExpansibleController _controller = ExpansibleController();

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('ExpansibleController.toggle'),
      ),
      body: Padding(
        padding: const EdgeInsets.all(16),
        child: Expansible(
          controller: _controller,
          headerBuilder: (context, animation) {
            return Card(
              child: ListTile(
                title: const Text('自定义 Expansible Header'),
                subtitle: const Text('底层展开组件，不限制 Material 样式'),
                trailing: RotationTransition(
                  turns: Tween<double>(
                    begin: 0,
                    end: 0.5,
                  ).animate(animation),
                  child: const Icon(Icons.expand_more),
                ),
                onTap: () {
                  _controller.toggle();
                },
              ),
            );
          },
          bodyBuilder: (context, animation) {
            return SizeTransition(
              sizeFactor: animation,
              child: const Card(
                child: Padding(
                  padding: EdgeInsets.all(16),
                  child: Text(
                    '这里是展开内容。'
                    'Expansible 更适合做完全自定义 UI，'
                    '而 ExpansionTile 是 Material 风格的封装。',
                  ),
                ),
              ),
            );
          },
        ),
      ),
      floatingActionButton: FloatingActionButton.extended(
        onPressed: () {
          _controller.toggle();
        },
        label: const Text('toggle'),
        icon: const Icon(Icons.swap_vert),
      ),
    );
  }
}

无障碍

ProgressIndicator

ProgressIndicator 的 semanticsValue 现在支持类似 50% 的百分比字符串，之前 progress bar 语义检查更偏向数值区间，现在对百分比文本有了明确支持：

const LinearProgressIndicator(
  value: 0.5,
  semanticsLabel: '文件上传进度',
  semanticsValue: '50%',
)

同样适用于 CircularProgressIndicator：

const CircularProgressIndicator(
  value: 0.75,
  semanticsLabel: '同步进度',
  semanticsValue: '75%',
)

Slider

Slider 修复了语义节点尺寸问题， _RenderSlider.assembleSemanticsNode 会把语义 rect 设置为以 thumb center 为中心、大小为 kMinInteractiveDimension 的区域：

Slider(
  value: volume,
  min: 0,
  max: 100,
  divisions: 20,
  label: '${volume.round()}',
  onChanged: (double value) {
    setState(() => volume = value);
  },
  semanticFormatterCallback: (double value) {
    return '音量 ${value.round()}%';
  },
)

其他还有：

PopupMenuButton 和 DropdownButton 的 expanded state 语义更新修复，避免展开状态没有正确同步
PinnedHeaderSliver 修复语义焦点捕获问题
不可见 semantics 节点从语义树中移除时的崩溃被修复
自动播放视频预览：通知用户是否已禁用视频预览的自动播放
优先使用不闪烁光标：允许 App 为那些觉得闪烁光标分散注意力或难以跟踪的用户提供稳定的、不闪烁的文本指示器
自动播放动画图像：检测用户何时选择暂停自动播放 GIF 或其他动画内容

最后

可以看出来，这个版本更新了很多，最核心就是样式库已经完成初步解耦落地，后续样式跟进和液态玻璃效果就能快很多了，同时这也是一个充满 AI Coidng 场景的更新，当然最可惜的还是桌面的依然不合并到 Stable ，虽然我已经用了一段时间了。

貌似关注过我的，基本已经提前看到大半的 3.44 更新了吧？

那么，更新吧骚年，是时候勇敢的吃螃蟹了。

2026 Google I/O ，意料之外的 Antigravity 2.0 和消失的 Gemini CLI

恋猫de小郭 — Wed, 20 May 2026 00:17:06 GMT

在刚刚过去的 Goolge I/O，其实我觉得最有意思的就是 Antigravity 2.0，虽然大家过去一年的时间里都在吐槽 Antigravity，但是现在它被扶正了，直接干掉了 Gemini CLI 这个绝对是大多数人意想不到的，果然青梅足马敌不过天降。

看来谷歌也知道 Gemini CLI 太垃圾了，所以把战略都转向 Antigravity ，这次 Antigravity 的定位是 agent-first development platform，这也是头部 AI Coding 产品里，最后一个 AI IDE 正式宣布放弃 IDEA 入口，转向 agent 管理入口了：

Codex App，Copilot App，Cursor 3，Trae Solo 都转向了 Agent 管理 UI ，这次 Antigravity 2.0 也是最后一个完成调整的了。

这一次 Antigravity 2.0 的核心是多个 agent 可以并行执行任务、生成代码、测试、验证、部署，同时跨 Google AI Studio、Android、Firebase 等开发场景协作。

说人话就是，以前的 Antigravity 是「带 Agent Manager 的 IDE」，而现在 Antigravity 2.0 则是「Agent 工作台 + CLI + SDK + 云端托管 Agent 的基础设施」。

现在的 Antigravity 2.0 不再强调说明代码补全，而是 standalone desktop application，核心在于「集中管理、定制和编排 coding agents」，你可以让 agent 进行代码重构、生成单元测试、按 spec 搭建服务组件，甚至从一个 prompt 派生 subagents，让多个任务并行运行。

这也是熟悉的场景了。

另外，2.0 支持 dynamic subagents for parallelized workflows ，也就是你发出一个复杂任务后，主 agent 自己会拆分出多个子 agent 并行处理不同部分，比如一个负责改后端，一个负责改前端，一个负责写测试，一个负责跑浏览器验证：

另外，这次还新增加了 Scheduled Tasks，也就是 Agent 可以后台自动跑任务，这就有点像 OpenClaw 场景了。

这次 2.0 支持的 scheduled tasks for background automation，就是可以让它按计划跑一些任务，例如定期检查 issue、跑测试、更新依赖、生成报告、重构某个模块、补测试覆盖。

这个方向其实和 Gemini Spark 的个人 agent 思路是同一条线，因为 Google 这次把 Spark 做成 24/7 后台 agent，而 Antigravity 则是提供 coding agent 平台能力，这两者都是属于「长期运行、可调度、可授权、可观察」的 agent 产品思想。

这页算是它和 Cursor / Copilot 目前最大区别之一，「The agent team in action, starting to build the OS」，例如官方展示的在构建自定义 Doom 操作系统的超大规模演示中（93 个子代理、15,000+ 次模型请求）：

Sentinel 子代理通过 Scheduled Tasks（后台 cron）持续监控其他子代理的进度文件
一旦某个子代理卡住（无限循环、编译卡死、I/O 阻塞），自动终止并重启，实现自我修复的多代理团队

在对话中输入 /schedule ，可设置一次性定时器或 recurring cron 计划，任务在后台异步运行（支持长期自主执行）

另外一个核心就是 Antigravity CLI，是的， Gemini CLI 凉了，现在是全新的 Antigravity CLI ，谷歌终于是发现自己的 Gemini CLI 不行了，而现在 Antigravity CLI 等于是把完整 Antigravity 能力下放到命令行：

same harness, same agent, same quality of intelligence as Antigravity 2.0。

另外它和 Claude 场景类似，能和桌面 app 深度集成，共享认证、上下文、skills 和配置，等于是 CLI 是 agent 的执行器，而 GUI 是 agent 的调度和审查的 GUI 场景。

同时你可以在 CLI 里启动、执行、快速交互，在桌面 app 里看任务、并行状态、artifact、审批，最后在 IDE 里做细节编辑，另外还可以用 SDK 把 agent 能力嵌入自己的平台。

需要注意的是，2026 年 6 月 18 日，Gemini CLI 和 Gemini Code Assist IDE 将停止使用。

另外，这次发布的还有 Antigravity SDK，Antigravity SDK 提供对 Google agent harness 的程序化访问，它可以让开发者定义 custom agent behaviors，并把它部署到自己选择的基础设施上。

import asyncio
from google.antigravity import Agent, LocalAgentConfig

async def main():
    config = LocalAgentConfig()
    async with Agent(config) as agent:
        response = await agent.chat("What files are in the current directory?")
        print(await response.text())

if __name__ == "__main__":
    asyncio.run(main())

所以这次发布的 Antigravity SDK，目的是为了让开发者基于 Google coding tool 构建 custom agents / custom workflows，这场景也和 Claude SDK 提供的如出一辙。

另外，这次还有 Managed Agents in Gemini API，Antigravity Agent 被云端 API 化，也就是说现在 Gemini API 支持 managed agents，开发者可以用一个 API call 启动一个能 reasoning、用工具、执行代码的 agent，它基于 Antigravity agent 驱动，基于 Gemini 3.5 Flash，可通过 Interactions API 和 Google AI Studio 使用。

官方目前列出的能力包括：

reason、plan、call tools
在 isolated Linux sandbox 里执行代码和管理文件
浏览 web 获取和处理实时数据
每次 interaction 可以创建或接收一个 environment
follow-up calls 可以恢复 session，保留文件和状态

这其实也很像「云端 Codex sandbox / Claude Code remote runner / OpenClaw-like agent runtime」的 Google 版本，区别是 Google 把它做进了 Gemini API，支持你用 AGENTS.md 和 SKILL.md 定义自己的 agent instruction、skills、data，并注册成 managed agent。

另外一个有意思的就是，这次 Google 给 AI Studio 加了 Antigravity export tool，也就是开发者可以把现有项目导出到本地 Antigravity，这次的产品思路很直观：

AI Studio：快速试想法 / prompt 原型 / Android vibe coding
Antigravity：接管工程化开发 / 多 agent 修改 / 测试验证

最后就是价格，这次谷歌新增加了 **Google AI Ultra $100/月** ，方案会给 Antigravity 比 Google AI Pro 高 5X 的使用限制，并且限时提供$ 100 Antigravity bonus credits ：

对应的 Ultra 现在是：

AI Ultra $100：面向开发者/高级用户，Antigravity 额度比 Pro 高 5X
AI Ultra $200：顶级方案，Gemini app 和 Antigravity 额度比 Pro 高 20X

比如这次的 Gemini Spark 就需要 AI Ultra ：

整体的方案价格如下所示：

Pro / Ultra 用户会有 priority access，额度每 5 小时刷新，而免费用户则改成更大的 weekly-based rate limit。

不过有点难以接受的是，这次官方强调 Antigravity 的用量不是按请求数或代码行数算，而是和 agent 做了多少“work”相关，简单任务消耗少，复杂推理任务消耗多，所以额度消耗还是一个迷之统计情况。

当然，Pro 肯定没事生产力就是了。

总的来说，这次 Google Antigravity 主要就是围绕了 Antigravity CLI、Antigravity SDK、Antigravity IDE 这个几个场景展开，当然也没什么太多新东西，更多是跟上了主流的节奏，不得不说谷歌的反应还是一如既往的慢，不过至少是跟上了，也算是憋了个大的。

那么，你更新了 Antigravity 2.0 了吗？？？