在日常开发里，我们经常要遍历和处理数据：

• 数组。
• Map、Set。
• 树形菜单。
• 评论树。
• 分页列表。

如果每一种数据结构，你都自己写一套遍历逻辑，那业务代码很快就会和数据结构细节绑死。

比如有的数据是扁平数组，有的数据是树结构，有的数据还得顺手过滤掉隐藏项。要是每次都在业务代码里手写 for 循环、递归、条件判断，那代码不仅不好复用，后面数据结构一变，遍历逻辑也得跟着改。

这种场景，就很适合用 迭代器模式。

1、迭代器模式定义

迭代器模式的定义是：提供一种方法顺序访问一个聚合对象中的各个元素，而又不暴露该对象的内部表示。

这句话听起来有点抽象，咱们把它翻译成人话，其实就是：

• 数据怎么存，集合自己知道。
• 数据怎么遍历，交给迭代器来处理。
• 使用者只需要一个统一的访问方式，不需要关心内部结构。

它的重点不在“存数据”，而在“把遍历这件事标准化”。

2、核心思想

1. 遍历逻辑和数据结构分离：业务代码不用知道集合内部到底是数组、树，还是别的什么结构。
2. 统一访问方式：不管底层怎么变，对外最好都提供差不多的遍历体验。
3. 不暴露内部细节：使用者只管拿数据，不用直接碰集合内部实现。

3、例子：树形菜单的统一遍历

在前端项目里，树形菜单特别常见，比如后台管理系统左侧那一坨菜单：

const menuTree = [
  {
    title: '工作台',
    hidden: false
  },
  {
    title: '订单管理',
    hidden: false,
    children: [
      {
        title: '订单列表',
        hidden: false
      },
      {
        title: '退款管理',
        hidden: true
      }
    ]
  },
  {
    title: '系统设置',
    hidden: false
  }
];

现在有个很常见的需求：把所有可见菜单依次渲染出来。

3.1 不用迭代器模式（业务代码自己递归）

如果不用迭代器模式，业务代码大概率就会先这么写：

function collectVisibleMenus(nodes, result = []) {
  // 先遍历当前层
  nodes.forEach(node => {
    if (!node.hidden) {
      result.push(node);
    }

    // 再递归遍历子节点
    if (node.children?.length) {
      collectVisibleMenus(node.children, result);
    }
  });

  return result;
}

const visibleMenus = collectVisibleMenus(menuTree);

visibleMenus.forEach(menu => {
  renderMenu(menu.title);
});

这样写当然能跑，但你很快就会发现几个问题：

1. 业务代码知道太多内部细节：它必须知道菜单数据里有 children 这个字段。
2. 遍历逻辑和业务逻辑耦合：递归遍历和“渲染菜单”揉在一起了。
3. 不方便切换遍历方式：如果后面你想改成广度优先遍历，或者遍历时顺手过滤掉禁用菜单，就还得继续改业务代码。

3.2 使用迭代器模式

更合理一点的做法是，把“怎么遍历树形菜单”这件事封装起来，对外只暴露统一的遍历能力。

class MenuCollection {
  constructor(tree = []) {
    this.tree = tree;
  }

  [Symbol.iterator]() {
    // 用栈实现一个深度优先遍历
    const stack = [...this.tree].reverse();

    return {
      next() {
        while (stack.length) {
          const current = stack.pop();

          if (current.children?.length) {
            // reverse 一下，保证遍历顺序和原始数据一致
            stack.push(...[...current.children].reverse());
          }

          if (current.hidden) {
            // 隐藏菜单跳过，但继续遍历它的子节点
            continue;
          }

          return {
            value: current,
            done: false
          };
        }

        return {
          value: undefined,
          done: true
        };
      }
    };
  }
}

const menus = new MenuCollection(menuTree);

for (const menu of menus) {
  renderMenu(menu.title);
}

这样改造之后，外部使用的人就不需要关心：

• 菜单是不是树结构。
• 子节点字段是不是叫 children。
• 遍历到底是递归实现还是栈实现。

使用者只需要写：

for (const menu of menus) {
  renderMenu(menu.title);
}

这就是迭代器模式最核心的价值：把“怎么遍历”封装起来，让使用者只关心“我拿下一个元素就行了”。

3.3 迭代器模式的灵活性

迭代器模式还有一个很实用的地方，就是后续很容易调整遍历策略。

比如现在我们实现的是深度优先遍历，如果后面需求改了，想换成广度优先遍历，那我们只需要改 MenuCollection 里的迭代逻辑，而不用去动外部使用代码。

也就是说：

• 对外使用方式不变。
• 对内遍历策略可以自由替换。

这其实和我们前面讲过的很多设计模式一样，核心目的都是尽量减少变化对外部代码的影响。

4、JavaScript 里的迭代器模式

其实在 JavaScript 里，迭代器模式你早就在用，只是很多时候没专门意识到。

比如：

• Array
• String
• Map
• Set
• NodeList

这些数据之所以都能被 for...of 遍历，本质上就是因为它们实现了迭代器相关协议。

const arr = ['Vue', 'React', 'Svelte'];
const iterator = arr[Symbol.iterator]();

console.log(iterator.next()); // { value: 'Vue', done: false }
console.log(iterator.next()); // { value: 'React', done: false }
console.log(iterator.next()); // { value: 'Svelte', done: false }
console.log(iterator.next()); // { value: undefined, done: true }

从这个例子里，我们顺手区分两个很容易混淆的概念：

4.1 什么是 iterator？

iterator 指的是迭代器对象，它最起码要提供一个 next() 方法。

每调用一次 next()，就返回一个对象：

• value：当前遍历到的值。
• done：是否遍历结束。

4.2 什么是 iterable？

iterable 指的是可迭代对象，也就是这个对象实现了 [Symbol.iterator]() 方法。

当你执行：

const iterator = arr[Symbol.iterator]();

本质上就是从一个 iterable 对象里，拿到了一个 iterator。

所以可以简单理解为：

• iterable：可以被迭代的对象。
• iterator：真正负责一次次往后取值的那个对象。

4.3 哪些语法在底层用到了迭代器？

像下面这些我们平时写得很顺手的代码，底层都和迭代器有关系：

const set = new Set([1, 2, 3]);

for (const item of set) {
  console.log(item);
}

console.log([...set]);
console.log(Array.from(set));

也就是说，for...of、扩展运算符 ...、Array.from() 等能力，背后都建立在迭代器机制之上。

5、生成器和迭代器模式的关系

很多同学看到这里，通常还会碰到另一个概念：Generator（生成器）。

它和迭代器模式也有很强的关系。

比如我们前面手写 MenuCollection 的时候，是自己返回了一个带 next() 方法的对象。其实在 JavaScript 里，我们也可以用生成器更省事地实现同样的效果：

class MenuCollection {
  constructor(tree = []) {
    this.tree = tree;
  }

  *[Symbol.iterator]() {
    const stack = [...this.tree].reverse();

    while (stack.length) {
      const current = stack.pop();

      if (current.children?.length) {
        stack.push(...[...current.children].reverse());
      }

      if (current.hidden) {
        continue;
      }

      // yield 可以理解为“产出当前值，并等待下一次继续”
      yield current;
    }
  }
}

这里的生成器写法，本质上还是在实现迭代器，只不过语法更简洁，看起来也更顺。

所以两者的关系可以这样理解：

• 迭代器模式：是一种设计思想，强调统一遍历方式、隐藏内部结构。
• 生成器：是 JavaScript 提供的一种语言机制，可以更方便地创建迭代器。

也就是说，生成器不是迭代器模式本身，但它经常是实现迭代器模式时一个特别顺手的工具。

6、迭代器模式的优缺点

6.1 优点：

• ✅ 简化使用方式：使用者不需要关心集合内部到底怎么存储、怎么遍历。
• ✅ 统一访问接口：不同类型的数据结构，可以尽量提供一致的遍历体验。
• ✅ 增强扩展性：后续更换遍历策略时，不容易影响外部代码。
• ✅ 符合单一职责原则：集合负责存数据，迭代器负责遍历数据。

6.2 缺点：

• ❌ 增加抽象层：如果数据结构本来就很简单，硬加一层迭代器可能有点过度设计。
• ❌ 调试成本上升：当遍历过程被封装起来后，定位某些遍历顺序问题时，可能要多看一层实现。
• ❌ 需要维护额外状态：像当前索引、遍历栈、队列等状态，都需要迭代器自己管理。

7、迭代器模式的应用

迭代器模式在前端和日常开发里其实特别常见，比如：

1. for...of 遍历数组、字符串、Map、Set。
2. 树形菜单、评论树、组织架构树等复杂结构的统一遍历。
3. 组件库里对数据源的封装，让外部只关心“拿下一个元素”。
4. 无限滚动、分页数据、流式数据的按需消费。
5. Generator、async iterator 这类机制，本质上也都和迭代思想密切相关。

小结

上面介绍了Javascript中非常经典的迭代器模式，它的核心思想就是：为集合提供统一的遍历方式，并且不暴露集合内部的实现细节。

对于前端开发来说，迭代器模式非常实用，像 for...of、Map、Set、树形菜单遍历、分页数据消费这些场景里，都能看到它的影子。它本质上就是帮我们把“怎么遍历”从“怎么使用数据”里拆开，这样代码会更清晰，后面改起来也更从容。

往期回顾

• JavaScript设计模式（一）：单例模式实现与应用
• JavaScript设计模式（二）：策略模式实现与应用
• JavaScript设计模式（三）：代理模式实现与应用
• JavaScript设计模式（四）：发布-订阅模式实现与应用
• JavaScript设计模式（五）：装饰者模式实现与应用
• JavaScript设计模式（六）：职责链模式实现与应用

在当今的前端开发中，性能优化已经成为项目上线前不可或缺的一环。本文将通过一个实际项目，系统性地介绍从构建优化到运行时优化的九大核心策略，帮助你打造一个高性能的Web应用。

1. 辅助分析插件：知己知彼，百战不殆

在进行任何优化之前，我们首先需要了解当前项目的性能瓶颈。辅助分析插件能够帮助我们量化问题，为后续优化提供数据支撑。

Webpack Bundle Analyzer

javascript

// webpack.config.js
const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;

module.exports = {
  plugins: [
    new BundleAnalyzerPlugin({
      analyzerMode: 'static', // 生成静态HTML文件
      openAnalyzer: false, // 构建完成后不自动打开
      reportFilename: 'bundle-report.html'
    })
  ]
};

这个插件会生成一个可视化的依赖关系图，让你清楚地看到每个模块的大小和占比，从而精准定位需要优化的模块。

Lighthouse CI

bash

npm install -g @lhci/cli

json

// lighthouserc.json
{
  "ci": {
    "collect": {
      "startServerCommand": "npm run start",
      "url": ["http://localhost:3000"],
      "numberOfRuns": 3
    },
    "assert": {
      "assertions": {
        "categories:performance": ["warn", {"minScore": 0.9}],
        "categories:accessibility": ["error", {"minScore": 0.95}]
      }
    }
  }
}

通过Lighthouse CI，我们可以在CI/CD流程中持续监控性能指标，确保每次代码提交都不会导致性能退化。

2. 压缩：让资源轻装上阵

压缩是性能优化中最直接有效的手段之一，能够显著减少资源传输体积。

JavaScript压缩

javascript

// webpack.config.js
const TerserPlugin = require('terser-webpack-plugin');

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        terserOptions: {
          compress: {
            drop_console: true, // 移除console
            drop_debugger: true, // 移除debugger
            pure_funcs: ['console.log'] // 移除特定函数
          },
          output: {
            comments: false // 移除注释
          }
        },
        parallel: true, // 多进程并行压缩
        extractComments: false // 不提取注释到单独文件
      })
    ]
  }
};

CSS压缩

javascript

const CssMinimizerPlugin = require('css-minimizer-webpack-plugin');

module.exports = {
  optimization: {
    minimizer: [
      new CssMinimizerPlugin({
        parallel: true,
        minimizerOptions: {
          preset: [
            'default',
            {
              discardComments: { removeAll: true },
              normalizeWhitespace: true,
              colormin: true
            }
          ]
        }
      })
    ]
  }
};

图片压缩

javascript

const ImageMinimizerPlugin = require('image-minimizer-webpack-plugin');

module.exports = {
  module: {
    rules: [
      {
        test: /.(jpe?g|png|gif|svg)$/i,
        type: 'asset',
        use: [
          {
            loader: ImageMinimizerPlugin.loader,
            options: {
              minimizer: {
                implementation: ImageMinimizerPlugin.imageminMinify,
                options: {
                  plugins: [
                    ['gifsicle', { interlaced: true }],
                    ['jpegtran', { progressive: true }],
                    ['optipng', { optimizationLevel: 5 }],
                    ['svgo', {
                      plugins: [
                        { name: 'removeViewBox', active: false },
                        { name: 'removeUselessStrokeAndFill', active: false }
                      ]
                    }]
                  ]
                }
              }
            }
          }
        ]
      }
    ]
  }
};

3. 样式：优雅的样式处理策略

样式的加载和渲染直接影响用户体验，合理的样式策略能够避免页面闪烁和样式冲突。

CSS Modules + PostCSS

javascript

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /.module.css$/,
        use: [
          'style-loader',
          {
            loader: 'css-loader',
            options: {
              modules: {
                localIdentName: '[name]__[local]--[hash:base64:5]'
              },
              importLoaders: 1
            }
          },
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: {
                plugins: [
                  require('autoprefixer'),
                  require('cssnano')({
                    preset: 'default'
                  })
                ]
              }
            }
          }
        ]
      }
    ]
  }
};

Critical CSS

关键CSS内联，非关键CSS延迟加载：

javascript

// critical-css.js
const critical = require('critical');

critical.generate({
  inline: true,
  base: 'dist/',
  src: 'index.html',
  target: 'index-critical.html',
  width: 1300,
  height: 900,
  penthouse: {
    blockJSRequests: false
  }
});

4. 环境变量：智能的环境配置

通过环境变量区分开发和生产环境，实现按需加载和配置。

环境变量配置

javascript

// webpack.config.js
const webpack = require('webpack');
const dotenv = require('dotenv');

module.exports = (env, argv) => {
  const isProduction = argv.mode === 'production';
  
  // 根据环境加载不同的环境变量
  const envConfig = dotenv.config({
    path: isProduction ? '.env.production' : '.env.development'
  }).parsed;
  
  const envKeys = Object.keys(envConfig).reduce((prev, next) => {
    prev[`process.env.${next}`] = JSON.stringify(envConfig[next]);
    return prev;
  }, {});
  
  return {
    plugins: [
      new webpack.DefinePlugin(envKeys),
      new webpack.EnvironmentPlugin(['NODE_ENV'])
    ]
  };
};

环境变量最佳实践

javascript

// config/index.js
export const config = {
  api: {
    baseURL: process.env.VUE_APP_API_URL,
    timeout: process.env.NODE_ENV === 'production' ? 10000 : 30000
  },
  logging: {
    level: process.env.NODE_ENV === 'production' ? 'error' : 'debug',
    enableConsole: process.env.NODE_ENV !== 'production'
  },
  features: {
    enableAnalytics: process.env.NODE_ENV === 'production',
    enableDebugTools: process.env.NODE_ENV !== 'production'
  }
};

5. Tree Shaking：消除无用代码

Tree Shaking能够自动移除未使用的代码，是构建优化的重要环节。

配置Tree Shaking

javascript

// webpack.config.js
module.exports = {
  mode: 'production',
  optimization: {
    usedExports: true, // 标记未使用的导出
    sideEffects: false, // 标记包是否包含副作用
    concatenateModules: true // 模块合并优化
  }
};

package.json配置sideEffects

json

{
  "name": "my-project",
  "sideEffects": [
    "*.css",
    "*.scss",
    "*.global.js"
  ]
}

使用ES Modules

确保代码使用ES Modules语法，避免使用CommonJS：

javascript

// ✅ 正确 - 支持Tree Shaking
import { debounce } from 'lodash-es';

// ❌ 错误 - 不支持Tree Shaking
import _ from 'lodash';

6. 代码分割：按需加载的艺术

代码分割能够有效减少初始加载时间，提升用户体验。

路由级别的代码分割

javascript

// React中使用React.lazy
import React, { lazy, Suspense } from 'react';

const Home = lazy(() => import('./pages/Home'));
const About = lazy(() => import('./pages/About'));
const Contact = lazy(() => import('./pages/Contact'));

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/about" element={<About />} />
        <Route path="/contact" element={<Contact />} />
      </Routes>
    </Suspense>
  );
}

Webpack智能分割策略

javascript

// webpack.config.js
module.exports = {
  optimization: {
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        // 将node_modules中的代码分离到vendors chunk
        vendors: {
          test: /[\/]node_modules[\/]/,
          name: 'vendors',
          priority: 10,
          chunks: 'all'
        },
        // 将公共组件分离到common chunk
        common: {
          name: 'common',
          minChunks: 2,
          priority: 5,
          reuseExistingChunk: true
        },
        // 分离React相关代码
        react: {
          test: /[\/]node_modules[\/](react|react-dom)[\/]/,
          name: 'react',
          priority: 20,
          chunks: 'all'
        }
      }
    },
    runtimeChunk: {
      name: 'runtime' // 将runtime代码分离
    }
  }
};

7. 组件封装：复用与性能的平衡

合理的组件封装能够提升代码复用性，同时避免不必要的性能损耗。

高阶组件与Render Props

javascript

// 性能监控HOC
function withPerformanceTracking(WrappedComponent) {
  return class extends React.Component {
    componentDidMount() {
      console.log(`${WrappedComponent.name} mounted`);
      performance.mark(`${WrappedComponent.name}_mount`);
    }
    
    componentWillUnmount() {
      performance.mark(`${WrappedComponent.name}_unmount`);
      performance.measure(
        `${WrappedComponent.name}_lifetime`,
        `${WrappedComponent.name}_mount`,
        `${WrappedComponent.name}_unmount`
      );
    }
    
    render() {
      return <WrappedComponent {...this.props} />;
    }
  };
}

// 懒加载组件封装
function LazyLoadComponent({ children, threshold = 0.1 }) {
  const [isVisible, setIsVisible] = useState(false);
  const ref = useRef();
  
  useEffect(() => {
    const observer = new IntersectionObserver(
      ([entry]) => {
        if (entry.isIntersecting) {
          setIsVisible(true);
          observer.disconnect();
        }
      },
      { threshold }
    );
    
    if (ref.current) {
      observer.observe(ref.current);
    }
    
    return () => observer.disconnect();
  }, [threshold]);
  
  return <div ref={ref}>{isVisible ? children : null}</div>;
}

8. 数据和图片懒加载：延迟加载的艺术

懒加载能够显著提升首屏加载速度，优化用户体验。

图片懒加载

javascript

// 自定义图片懒加载Hook
function useLazyImage(src, placeholder = 'data:image/svg+xml,...') {
  const [imageSrc, setImageSrc] = useState(placeholder);
  const [imageRef, setImageRef] = useState();
  
  useEffect(() => {
    if (!imageRef) return;
    
    const observer = new IntersectionObserver(
      ([entry]) => {
        if (entry.isIntersecting) {
          const img = new Image();
          img.onload = () => {
            setImageSrc(src);
          };
          img.src = src;
          observer.disconnect();
        }
      },
      { rootMargin: '50px' }
    );
    
    observer.observe(imageRef);
    
    return () => observer.disconnect();
  }, [src, imageRef]);
  
  return [imageSrc, setImageRef];
}

// 使用示例
function LazyImage({ src, alt }) {
  const [imageSrc, ref] = useLazyImage(src);
  
  return (
    <img 
      ref={ref}
      src={imageSrc}
      alt={alt}
      loading="lazy" // 浏览器原生懒加载
    />
  );
}

数据懒加载

javascript

// 无限滚动数据加载
function useInfiniteScroll(fetchData, options = {}) {
  const [data, setData] = useState([]);
  const [loading, setLoading] = useState(false);
  const [hasMore, setHasMore] = useState(true);
  const [page, setPage] = useState(1);
  
  const observer = useRef();
  const lastElementRef = useCallback(node => {
    if (loading) return;
    if (observer.current) observer.current.disconnect();
    
    observer.current = new IntersectionObserver(entries => {
      if (entries[0].isIntersecting && hasMore) {
        setPage(prevPage => prevPage + 1);
      }
    });
    
    if (node) observer.current.observe(node);
  }, [loading, hasMore]);
  
  useEffect(() => {
    setLoading(true);
    fetchData(page, options).then(newData => {
      setData(prev => [...prev, ...newData]);
      setHasMore(newData.length > 0);
      setLoading(false);
    });
  }, [page, fetchData, options]);
  
  return { data, loading, lastElementRef, hasMore };
}

9. 使用CDN：加速全球访问

CDN能够将静态资源分发到全球边缘节点，大幅提升资源加载速度。

配置CDN

javascript

// webpack.config.js
module.exports = {
  output: {
    publicPath: process.env.NODE_ENV === 'production' 
      ? 'https://cdn.example.com/assets/'
      : '/',
    filename: '[name].[contenthash].js'
  },
  
  externals: {
    react: 'React',
    'react-dom': 'ReactDOM',
    vue: 'Vue',
    lodash: '_',
    axios: 'axios'
  }
};

HTML中引入CDN资源

html

<!DOCTYPE html>
<html>
<head>
  <!-- 预连接CDN域名 -->
  <link rel="preconnect" href="https://cdn.example.com">
  <link rel="dns-prefetch" href="https://cdn.example.com">
  
  <!-- 使用SRI保证资源完整性 -->
  <link 
    rel="stylesheet" 
    href="https://cdn.example.com/main.css"
    integrity="sha384-..."
    crossorigin="anonymous"
  >
</head>
<body>
  <div id="app"></div>
  
  <!-- 异步加载非关键脚本 -->
  <script 
    src="https://cdn.example.com/analytics.js"
    async
    defer
  ></script>
</body>
</html>

CDN最佳实践

javascript

// 动态加载CDN资源
class CDNLoader {
  static loadScript(src, integrity) {
    return new Promise((resolve, reject) => {
      const script = document.createElement('script');
      script.src = src;
      script.integrity = integrity;
      script.crossOrigin = 'anonymous';
      script.onload = resolve;
      script.onerror = reject;
      document.head.appendChild(script);
    });
  }
  
  static async loadVendors() {
    const vendors = [
      { src: 'https://cdn.example.com/react.js', integrity: 'sha384-...' },
      { src: 'https://cdn.example.com/react-dom.js', integrity: 'sha384-...' }
    ];
    
    await Promise.all(vendors.map(v => this.loadScript(v.src, v.integrity)));
  }
}

// 在应用启动前加载CDN资源
if (process.env.NODE_ENV === 'production') {
  CDNLoader.loadVendors().then(() => {
    // 启动应用
    import('./app');
  });
}

总结：性能优化的系统化思考

性能优化不是一蹴而就的工作，而是一个持续迭代的过程。通过上述九大策略的系统化应用，我们能够构建出高性能、高可用的现代Web应用：

1. 分析先行：使用Bundle Analyzer和Lighthouse量化问题
2. 资源压缩：通过多种压缩技术减小资源体积
3. 样式优化：合理处理CSS加载策略
4. 环境区分：根据不同环境做差异化配置
5. 代码消除：通过Tree Shaking移除无用代码
6. 按需加载：代码分割实现精准加载
7. 组件复用：封装高性能可复用组件
8. 延迟策略：数据和图片懒加载提升首屏速度
9. 网络加速：CDN提升全球访问体验

记住，性能优化的核心原则是：在保证功能完整性的前提下，最小化资源传输和处理时间，最大化用户体验。希望本文的实战经验能够帮助你在实际项目中更好地进行性能优化。

还在发愁只会简单地调用 LLM API，不知道如何将 AI 技术落地到复杂的真实业务中吗？

今天和大家分享一个刚刚开源的完整硬核项目：AI Data Analyzer (自动化数据分析 AI Agent)！不仅开源了全部代码，还配有全网最详尽的「保姆级」全栈图文教程！

💡 这是一个什么项目？

这是一个基于（Next.js + Nest.js）构建的全栈自动化数据分析平台。它结合了大语言模型（LLM），实现了从数据上传 ➡️ 自动化清洗 ➡️ 智能分析 ➡️ 可视化图表呈现的完整数据处理管道。它不是一个简单的玩具，而是按照工业级标准设计的企业级 AI 应用雏形！

🔥 核心亮点：

• 🛠 最前沿的全栈技术栈：前端 Next.js (App Router) + React 19 + TailwindCSS v4；后端 NestJS + PostgreSQL + TypeORM。
• 🤖 多模型自由切换：统一的 ILLMService 接口，零成本切换 OpenAI、Claude，甚至支持本地部署部署模型 (Ollama + Qwen)。
• ⚡️ 极致的实时交互体验：结合 SSE (Server-Sent Events) 实现打字机流式输出，结合 WebSocket 实时推送 AI Agent 的底层思考与执行步骤！
• ⏳ 工业级高并发设计：接入 Redis + BullMQ 构建异步任务队列，支持海量数据后台处理，主流程丝滑不阻塞。
• 📊 酷炫的 2D/3D 进阶可视化：告别枯燥表格！集成 ECharts 和 Three.js (React Three Fiber)，实现多维数据雷达图、AI 关系力导向图谱，甚至 3D 数据星系交互！
• 🛡 严谨的数据与反馈机制：使用 Zod + class-validator 解决 AI 幻觉重试，并内置了人类反馈接口 (RLHF 基础) 打造数据飞轮。

📚 配套系列教程

只看源码太枯燥？没关系！项目配套了 《使用 Next.js 与 Nest.js 构建自动化数据分析 AI Agent》 系列长文教程。从架构设计、环境搭建、大模型对接，到前端可视化仪表盘、异步队列实战，手把手带你打通全栈 AI 链路！

🔗 传送门

• 💻 GitHub 源码地址：github.com/you-want/ai…
• 📖 配套系列教程：点击查看系列文章合集 / 微信公众号链接

欢迎大家 Star ⭐️ 关注、Fork 把玩，也期待提交 PR 一起完善！如果有任何问题，欢迎在评论区或 Issue 中交流讨论～ 👇👇👇

本文对应项目版本：v0.0.7

在 v0.0.6 里，我已经把项目从单 Tool Calling 推进到了 Multi-Tool Runtime：

• calculator
• datetime
• text-transform
• Tool Registry
• 前端多 Tool 卡片展示
• 最近 N=8 轮上下文窗口

走到这一步后，我发现项目开始进入另一个更像工程问题的阶段：

当系统里已经有多个 Tool 之后，下一步到底应该继续堆 Tool，还是先往上抽一层更稳定的能力封装？

这就是 v0.0.7 想回答的问题。

这一版我没有直接去做 Agent，也没有急着接 MCP，而是先做了一件更克制、但我认为更关键的事：

在现有的 Multi-Tool Runtime 之上，长出第一层 Skill Runtime。

这篇文章主要讲 4 件事：

1. 为什么现在做 Skill 是合适的
2. utility-skill 到底解决了什么问题
3. Runtime 怎么接 Skill，而不是把它做成另一套散乱逻辑
4. 为什么 Prompt 很重要，但版本主题仍然要保持克制

项目主界面截图

Skill Runtime 链路图

用户输入
  -> /api/chat
    -> 读取 options.skill
      -> SkillRegistry 获取 skill 定义
        -> allowedTools 过滤 ToolRegistry
        -> 注入 skill.systemPrompt
          -> 模型 planning
            -> 选择 tool_call
              -> Runtime 校验/执行 tool
                -> tool result 回填
                  -> 最终回答流式返回前端

为什么 v0.0.7 不直接做 Agent

这件事必须先讲清楚。

因为从版本节奏上看，v0.0.6 做完之后，很容易产生一种冲动：

• 既然已经有多个 Tool 了，是不是下一步就该直接做 Agent？
• 是不是该把 Skill、MCP、记忆、任务规划一起拉进来？

我最后没有这么做，原因其实很简单：

• v0.0.5 验证的是：单 Tool Calling 可不可行
• v0.0.6 验证的是：Multi-Tool Runtime 能不能站住
• 到了 v0.0.7，更值得验证的是：Tool 之上能不能再稳定长出一层能力模式

如果这时直接跳去做 Agent，会把很多变量混在一起：

• Tool 选择是否稳定
• Tool Runtime 是否清晰
• Prompt 约束是否足够
• 是否需要多步计划
• 是否需要记忆系统
• 是否需要外部能力接入

这些问题一旦一起出现，版本主题很容易被冲散。

所以我给 v0.0.7 定下的边界非常明确：

1. 只落一个正式 Skill：utility-skill
2. 新增一个 Tool：unit-convert
3. 不做 Skill UI
4. 不做自动 Skill 路由
5. 不做 Agent Loop
6. 不做 MCP 接入

一句话概括：

这一版不是为了证明“系统更聪明了”，而是为了验证：Tool Runtime 之上，能不能再稳定长出第一层 Skill Runtime。

这版到底解决了什么问题

v0.0.6 做完之后，项目已经有了多个 Tool，但也暴露了一个很真实的问题：

1. Tool 还是“散着的能力”

虽然已经有：

• calculator
• datetime
• text-transform

但它们本质上还是一组分散的原子能力。系统并没有一层更高的语义去表达：

• 当前是在什么任务模式下工作
• 当前允许使用哪些 Tool
• 当前回答应该更偏“结果优先”还是“解释优先”

2. 多 Tool 之后，Prompt 开始越来越重要

比如下面这些问题：

• 357×28+999+1 等于多少
• 今天是周几
• 提取这段文本里的链接

按理说都应该优先走 Tool。但如果没有一层更清晰的能力模式约束，模型很容易出现这些行为：

• 自己先口算
• reasoning 里说“应该调用工具”，但没真正发起 tool_call
• 输出风格越来越散

3. 我需要一层更高的“能力模式”

如果继续在 chat-service.ts 里堆更多 Tool 特判，最后只会让 Runtime 越来越重。

真正需要的，是一层更高的东西，让系统能够明确知道：

• 当前属于哪类能力域
• 当前允许哪些 Tool
• 当前输出应该是什么风格

这个东西，就是这一版里的 Skill。

Skill 在这里到底是什么

我对 Skill 的理解，不是“另一个 Tool”，也不是“精简版 Agent”。

它更像是：

站在 Tool 之上的一层高阶能力模式。

在 v0.0.7 里，我刻意让 Skill 只承担很克制的职责：

• 定义一个任务域
• 提供一段 system prompt
• 限制当前允许使用的 Tool 集
• 约束输出策略

它不直接执行 Tool，也不负责多步规划。

这点很重要，因为我不想让 Skill 偷偷长成 Agent。

为什么是 utility-skill

第一版 Skill 我没有做 research-skill，也没有做 writer-skill，而是选了一个更克制的方向：

• utility-skill

它对应的是一类非常具体的任务：

• 精确计算
• 时间与日期处理
• 文本转换与提取
• 单位换算

我选它主要有三个原因。

1. 它和当前 Tool 集天然衔接

v0.0.6 已经有：

• calculator
• datetime
• text-transform

这些 Tool 天然就属于“日常实用任务”的一部分。

所以 utility-skill 不是硬造出来的抽象，而是从当前 Tool 集里自然长出来的。

2. 它足够轻，但足够证明 Skill 是成立的

它不需要：

• 外部系统
• MCP
• 复杂记忆
• Agent Loop

但它足够证明一件很重要的事：

Skill 不是一段 Prompt，而是一层真的会影响 Runtime 的能力定义。

3. 它能继续长，但不会把版本做散

如果第一版就做 research-skill，很快就会牵扯到：

• 搜索
• 抓取
• 来源引用
• 多步编排

而 utility-skill 足够小，刚好能帮我验证 Skill Runtime 的骨架，不会把版本主题拉散。

总体架构：在 Multi-Tool Runtime 之上再加一层 Skill

这一版的主链路长这样：

用户输入
  -> 前端页面
    -> /api/chat
      -> chat-service
        -> Skill Registry
        -> Tool Registry
        -> ChatOllama
          -> tool calling / tool execution
            -> NDJSON stream
              -> useChatStream
                -> reasoning / tool / text 渲染

Skill Runtime 总体链路图

flowchart LR
    A["用户请求"] --> B["/api/chat"]
    B --> C["命中 Skill"]
    C --> D["读取 SkillDefinition"]
    D --> E["限制可用 Tools"]
    E --> F["模型选择是否调用 Tool"]
    F --> G["Runtime 执行 Tool"]
    G --> H["组合最终结果"]
    H --> I["流式返回前端"]

如果用一句话概括，就是：

Tool 负责原子能力，Skill 负责高层能力模式，Runtime 负责把两者接起来。

这一版里最关键的变化不是“多了一个 unit-convert”，而是：

• Runtime 先感知 Skill
• 再决定当前可用 Tool 集
• 再把这套能力边界交给模型

Tool 之上再加一层 Skill，最重要的是 Registry

如果想让 Skill 成为正式能力层，第一步就不能继续把相关逻辑散落在 chat-service.ts 里。

所以我先做的是：把 Skill 和 Tool 一样，也收进 Registry。

关键代码：Skill 的统一定义接口

这段代码的作用是：让 Skill 也成为一个可注册、可查询、可扩展的能力单元。

export type SkillOutputPolicy = 'concise-utility'
export type SkillResultPolicy = 'tool-first'

export interface SkillDefinition {
  name: string
  description: string
  systemPrompt: string
  allowedTools: string[]
  outputPolicy?: SkillOutputPolicy
  resultPolicy?: SkillResultPolicy
  routingHints?: string[]
  isAvailable?: () => boolean
}

这里我最看重的，不是 name 和 systemPrompt，而是下面这些字段：

• allowedTools
• outputPolicy
• resultPolicy
• routingHints

它们决定了 Skill 不是“模型的一段额外说明”，而是 Runtime 可以真正感知的一层能力配置。

关键代码：Skill Registry

这段代码的作用是：让 Runtime 只通过统一入口读取 Skill，而不是在主流程里到处判断具体 Skill 名称。

export interface ChatSkillRegistry {
  list(): SkillDefinition[]
  listActive(): SkillDefinition[]
  get(name: string): SkillDefinition | undefined
}

export function createChatSkillRegistry(skillDefinitions: SkillDefinition[]): ChatSkillRegistry {
  const skillDefinitionMap = new Map(
    skillDefinitions.map(skillDefinition => [skillDefinition.name, skillDefinition])
  )

  return {
    list() {
      return skillDefinitions
    },
    listActive() {
      return skillDefinitions.filter(skillDefinition => skillDefinition.isAvailable?.() ?? true)
    },
    get(name: string) {
      return skillDefinitionMap.get(name)
    },
  }
}

这一步其实是在为后面的演进打基础：

• 今天是 utility-skill
• 后面可以是 research-skill
• 再往后甚至可以有 MCP-based skill

但 Runtime 主链不需要被这些具体名字污染。

utility-skill 是怎么定义的

这一版里，utility-skill 并没有做什么“神秘编排”，它做的事情非常务实：

• 定义任务域
• 指定允许使用的 Tool
• 用 Prompt 约束输出风格

关键代码：utility-skill definition

这段代码的作用是：把“日常实用任务”正式定义成一层 Skill。

export const utilitySkillDefinition: SkillDefinition = {
  name: 'utility-skill',
  description: '处理日常确定性实用任务的稳定能力层',
  systemPrompt: `...`,
  allowedTools: ['calculator', 'datetime', 'text-transform', 'unit-convert'],
  outputPolicy: 'concise-utility',
  resultPolicy: 'tool-first',
  routingHints: [
    'math',
    'date',
    'time',
    'weekday',
    'relative-date',
    'convert',
    'markdown-to-text',
    'extract-links',
    'json-format',
    'unit-conversion',
  ],
}

这里最关键的有两个点。

1. allowedTools

这一版里 Skill 的价值不只是“多一段 Prompt”，而是它会真的影响当前 Runtime 的可用能力边界。

也就是说，在 utility-skill 下，当前允许给模型看到的 Tool，就是这四个：

• calculator
• datetime
• text-transform
• unit-convert

2. tool-first

我给 utility-skill 选的结果策略是：

• tool-first

原因很简单，这类任务本来就是高度确定性的：

• 计算
• 日期
• 单位换算

如果模型已经拿到了 Tool 结果，再让它自由发挥，反而更容易把答案写歪。

Runtime 怎么真正接 Skill

Skill 真正有价值的地方，不在 definition 文件，而在于 Runtime 会不会把它接进去。

关键代码：请求里读取 Skill

这段代码的作用是：让 Skill 成为正式请求参数，而不是隐含状态。

function resolveRequestedSkill(request: ChatRequest): SkillDefinition | undefined {
  const skillName = request.options?.skill?.trim()

  if (!skillName) {
    return undefined
  }

  const skillDefinition = getChatSkillDefinition(skillName)

  if (!skillDefinition || !(skillDefinition.isAvailable?.() ?? true)) {
    throw createInvalidSkillError(skillName)
  }

  return skillDefinition
}

这里我刻意让 skill 以 options.skill 的方式显式传入，而不是让系统自动猜当前该用哪个 Skill。

这是一个刻意的版本边界控制：

• 先验证 Skill Runtime 本身
• 暂时不把“Skill 路由”这个变量引进来

关键代码：按 Skill 过滤当前 Tool 集

这段代码的作用是：让 Skill 真实改变当前 Runtime 的可用能力边界。

function getActiveToolDefinitions(skillDefinition?: SkillDefinition): ChatToolDefinition[] {
  const activeToolDefinitions = chatToolRegistry.listActive()

  if (!skillDefinition) {
    return activeToolDefinitions
  }

  const allowedToolNames = new Set(skillDefinition.allowedTools)

  return activeToolDefinitions.filter(toolDefinition => allowedToolNames.has(toolDefinition.name))
}

这一步非常关键，因为它说明：

• Skill 不是文本层能力
• Skill 是 Runtime 层能力

后面如果你要接 MCP、接更多 Skill，这种边界会非常有价值。

为什么还要新加 unit-convert

如果这一版只做 utility-skill，而不再新增任何 Tool，那它看起来会很像：

• 把现有 Tool 打包进一个 Skill

这会让 Skill 的存在感偏弱。

所以我在 v0.0.7 里又补了一个很合适的新 Tool：

• unit-convert

它的价值在于：

• 和 calculator / datetime / text-transform 一样，都是确定性任务
• 非常贴近日常实用场景
• 能让 utility-skill 更像一个完整的实用能力包

关键代码：unit-convert 的 schema

这段代码的作用是：让单位换算成为一个边界明确、可校验、可扩展的 Tool。

const unitConvertToolSchema = z.object({
  value: z.number().finite(),
  from: z.enum(supportedUnits),
  to: z.enum(supportedUnits),
})

这一版我刻意把范围控制得很小，只支持：

• 长度
• 重量
• 温度

没有去碰：

• 货币汇率
• 存储单位
• 实时换算

因为 v0.0.7 的重点不是“功能越多越好”，而是“Skill Runtime 是否站得住”。

关键代码：unit-convert 的 definition

这段代码的作用是：把 unit-convert 纳入统一 Tool Runtime，并声明它的结果是权威结果。

export const unitConvertToolDefinition: ChatToolDefinition<z.infer<typeof unitConvertToolSchema>> = {
  name: 'unit-convert',
  tool: unitConvertTool,
  schema: unitConvertToolSchema,
  normalizeArgs: normalizeUnitConvertToolArgs,
  formatInput: formatUnitConvertToolInput,
  getDisplayConfig: args => ({
    title: 'unit-convert',
    action: 'convert',
    inputPreview: formatUnitConvertToolInput(args),
  }),
  resultIsAuthoritative: true,
}

这里的 resultIsAuthoritative = true 很重要。

因为单位换算和计算题一样：

Tool 结果应该被视为权威事实，而不是让模型再自由改写。

这一版最真实的坑：Prompt 很重要，但版本主题也要克制

如果只看实现结构，v0.0.7 好像已经很完整了。

但真正做下来之后，我觉得最值得写的，反而是一个很现实的工程结论：

Prompt 很重要，但版本不能为了追求“更稳”就把一切都做成特判。

在 datetime 这种时间类问题上，我确实做过多轮 Prompt 收紧尝试，比如：

• 明确要求时间、日期、星期问题优先使用 datetime
• 禁止模型在 reasoning 里只说“应该调用工具”却不真正发起 tool_call

这些约束是有价值的，但我最后没有把这版写成“到处加特定问题兜底”的版本。

原因是 v0.0.7 的主题是：

• 验证 Skill Runtime 是否成立

而不是：

• 把所有边界问题都靠局部补丁兜住

这也是为什么当前版本保留的是：

• Skill Registry
• allowedTools
• 统一 prompt 约束
• Runtime 主链校验与错误透传

而不是把每一个相对日期表达都变成运行时特判。

前端这版最大的变化：现在渲染的是 Skill 下的 Tool 事件流

前端这版没有做新的 Skill UI，这是我故意的。

因为 v0.0.7 的重点不在“多一个标签”，而在于：

• Skill 已经真实影响 Runtime
• 前端仍然可以通过现有 reasoning / tool / text 协议感知这一变化

所以前端这一版主要延续的是：

• useChatStream 消费结构化流
• Tool card 显示工具调用过程
• Skill 通过请求中的 options.skill 默认启用

关键代码：前端默认启用 utility-skill

这段代码的作用是：让 /instamind 默认工作在 utility-skill 模式下。

const DEFAULT_SKILL = 'utility-skill'

const requestBody: ChatRequest = {
  conversationId: conversationIdRef.current,
  messages: buildRequestMessages(nextMessages),
  options: {
    model: DEFAULT_MODEL,
    enableReasoning: true,
    skill: DEFAULT_SKILL,
  },
}

这一点让我能在不加新 UI 的情况下，先把 Skill Runtime 验证起来。

这版的真实回归，最说明问题的是什么

v0.0.7 我没有只看“代码能编译通过”，还单独做了一轮真实回归。

回归里比较关键的结论有这些：

稳定的部分

• 普通开放式问答正常
• calculator 正常
• datetime(action=now) 正常
• unit-convert 正常
• text-transform 正常输入路径可用
• 非法 JSON 会返回 tool-error

最说明版本边界的部分

• utility-skill 已经能真实约束 Tool 使用范围
• 多 Tool 仍然可以在 Skill 下保持统一输出风格
• 但某些边界场景是否继续做更强兜底，已经不是这版的主问题，而是下一版是否继续打磨的问题

这个结论对我来说非常重要，因为它意味着：

v0.0.7 已经把 Skill Runtime 这条主链真正接通了，而版本主题也还保持清晰。

当前边界：这版已经做到了什么，还没做到什么

已经做到的

• Skill Definition / Skill Registry 已落地
• utility-skill 已能真实约束 Runtime
• unit-convert 已接入
• 版本材料和回归记录已同步

还没做的

• 自动 Skill 路由
• 多 Skill 串联
• Skill 级记忆
• Skill UI
• MCP 接入
• Agent 化执行

这些都不是遗漏，而是我在这版里刻意没做。

因为这篇文章真正想讲清楚的，不是“系统又多厉害了”，而是：

版本边界控制本身，就是 Runtime 架构能力的一部分。

这一版我最想留下的结论

如果要用一句话概括 v0.0.7，我会写：

这不是“多加一个 unit-convert”的版本，而是项目第一次正式把 Tool Runtime 往上抬了一层，长出了第一层 Skill Runtime。

再具体一点，这一版最值得记住的 4 个结论是：

1. 多 Tool 之后，真正的难点不再是“能不能调 Tool”，而是“能不能稳定管理 Tool 边界”
2. Skill 的价值不在于多一段 Prompt，而在于它是否真实约束了 Runtime
3. 版本主题清晰，比把所有边界问题都塞进同一版更重要
4. Tool、Skill、MCP、Agent 更像一条能力演进链，而不是并列功能清单

下一步会往哪走

如果继续往后推进，我觉得最自然的方向不会是立刻做 Agent，而是：

• 继续收口 utility-skill
• 评估下一版是继续做更多 Skill，还是进入 MCP 试点

如果说 Tool 是原子能力，Skill 是能力模式，那么下一步就会开始进入：

• 外部能力接入标准
• 更高层的任务模式
• 更完整的 Agent Runtime

但那已经是后面的故事了。

最后

这个项目还会继续沿着 Skill Runtime、MCP、Agent Runtime 这些方向迭代下去。

如果这篇文章对你有帮助，欢迎到 GitHub 看看项目，也欢迎顺手点个 Star，这会是我继续更新下去的很大动力。

仓库地址： github.com/HWYD/ai-min…

如果你已经会调用大模型、也知道 tool calling 和 agent 的基本概念，那接下来最值得看的问题通常不是“怎么再包一层 prompt”，而是：一个真正能跑任务的 agent，到底是怎么在代码里运转起来的。

这篇文章不从抽象定义讲起，而是直接从 Claude Code 的实现思路切入，拆解它最核心的一条执行主线：Agent Loop。

1. 什么是 Agent Loop

一句话：Agent Loop 是让模型从“一次回答”升级为“持续决策系统”的控制循环。

你可以把它理解成一个回合制 runtime，每一回合都做同样的事情：

1. 读取当前上下文；
2. 调用模型生成动作意图；
3. 如果有工具调用就执行工具；
4. 把工具结果写回上下文；
5. 判断是否进入下一回合。

这个循环停止时，系统才真正产出“任务完成态”的结果，而不是中间状态。

2. 最小可用模型：先跑通闭环

先看一个最小版本：

let messages = [userMessage];

while (true) {
  const assistant = await callModel(messages);
  messages.push(assistant);

  const toolUses = extractToolUseBlocks(assistant);
  if (toolUses.length === 0) {
    break;
  }

  const toolResults = await runTools(toolUses);
  messages.push(...toolResults);
}

return buildFinalAnswer(messages);

这段代码虽然简单，但已经包含了 agent 的本质：

• 状态是累积的：不是每次从零思考；
• 决策是迭代的：不是一轮生成定生死；
• 外部世界可进入推理链：工具结果会回流给模型。

如果你只能记住一个原则，就是这个：
工具结果不是“展示给用户就完了”，而是“下一轮推理输入”。

3. 真实实现的主流程

在工程实现里，Agent Loop 一般会拆成“外层编排 + 内层循环 + 模型流式适配”三层：

flowchart TD
    A["Orchestrator（会话编排）"] --> B["Agent Loop（回合循环）"]
    B --> C["Model Stream（流式消息）"]
    C --> D{"是否出现 tool_use?"}
    D -- "是" --> E["执行工具并产出 tool_result"]
    E --> B
    D -- "否" --> F["结束循环并输出结果"]

这种分层有个明显好处：
你可以在不改核心循环逻辑的前提下，替换模型供应商、切换工具执行策略，或者接入远端会话。

这句话可以拆开理解。

核心循环真正关心的，其实只有几件事：

1. 当前消息上下文是什么；
2. 这一轮模型产出了什么事件；
3. 有没有 tool_use；
4. 工具结果什么时候回流；
5. 当前任务是否应该继续下一轮。

也就是说，Agent Loop 关心的是“控制流程”，而不是某个具体实现细节。

比如：

• 如果你把底层模型从 Anthropic 换成 OpenAI，只要新的模型适配层仍然能把输出整理成统一的消息事件流，循环本身就不需要重写。
• 如果你把工具执行从“串行执行”换成“并发执行”或“流式执行”，只要工具结果最终还是按统一格式回到消息链，循环判断逻辑也不用变。
• 如果你把运行方式从“本地单进程”换成“远端 agent 会话”，只要远端返回的消息还能被还原成同一套 assistant、tool result、status 事件，循环依然可以照常推进。

所以这层设计的关键价值是“隔离变化”：

• 上层编排器负责会话和运行环境；
• 中间的 Agent Loop 负责任务推进；
• 下层适配器负责模型协议、工具协议、远端通信。

这样一来，变化最多的部分被压到了外围，最核心的循环本身反而能保持稳定。

4. 一个回合是怎么结束的：Claude Code 如何做健壮收口

这一节其实只想说明一个核心点：在 Claude Code 里，“这一轮没有新的工具调用了”并不等于“立刻结束”。

真正的逻辑是：

1. 先看这一轮是否还需要 follow-up；
2. 如果不需要，也不会马上返回；
3. 系统会先尝试几条恢复路径；
4. 只有恢复都失败了，才真正结束这一轮。

先看续轮判断本身。在 query.ts 里，Claude Code 还是会先根据消息内容里的真实 tool_use 来设置 needsFollowUp：

// query.ts
const toolUseBlocks: ToolUseBlock[] = [];
let needsFollowUp = false;

const msgToolUseBlocks = message.message.content.filter(
  content => content.type === 'tool_use',
) as ToolUseBlock[];

if (msgToolUseBlocks.length > 0) {
  toolUseBlocks.push(...msgToolUseBlocks);
  needsFollowUp = true;
}

但关键在后面。Claude Code 的健壮性，不在于它会判断 needsFollowUp，而在于它在 !needsFollowUp 时不会立刻退出，而是先检查“这次能不能修一修再继续跑”。

把这一段抽象后，可以写成下面这样：

// src/query.ts - 简化后的退出/恢复逻辑
if (!needsFollowUp) {
  const lastMessage = assistantMessages.at(-1);

  // 恢复路径 1: Prompt 太长 -> 尝试上下文折叠
  if (isPromptTooLongMessage(lastMessage)) {
    const drained = contextCollapse.recoverFromOverflow(messages);
    if (drained.committed > 0) {
      state.messages = drained.messages;
      continue;
    }

    // 恢复路径 2: 响应式压缩
    if (!state.hasAttemptedReactiveCompact) {
      const compacted = reactiveCompact(messages);
      state.messages = compacted;
      state.hasAttemptedReactiveCompact = true;
      continue;
    }
  }

  // 恢复路径 3: max_tokens 截断 -> 增加 token 预算
  if (lastStopReason === 'max_tokens') {
    state.maxOutputTokensOverride = currentLimit * 2;
    state.maxOutputTokensRecoveryCount++;
    continue;
  }

  // 真正退出
  return { reason: 'end_turn' };
}

这段逻辑最值得注意的地方是连续的三个 continue。

它说明 Claude Code 对“结束”这件事的态度不是保守退出，而是优先恢复：

• 如果是 prompt 太长，先尝试上下文折叠；
• 折叠不够，再尝试响应式压缩；
• 如果是输出被 token 上限截断，再提高 token 预算重试；
• 只有这些恢复路径都走不通，才真正返回 end_turn。

所以这一节真正想表达的就是一句话：

在 Claude Code 里，一个回合结束不是“没工具了就退出”，而是“没工具了之后，先把能恢复的情况恢复掉，恢复不了才结束”。

这就是它和普通 demo 的差别。demo 往往只会判断“继续还是退出”，而 Claude Code 还多做了一层“退出前恢复”，因此在长上下文、输出截断这类真实问题面前，循环不会轻易中断。

5. queryLoop 才是真正的发动机，它的流式输出是“按消息块”推进的

如果说 Agent Loop 的概念骨架是 while (true)，那真正让 Claude Code 跑起来的，是 queryLoop 这种“边接收、边判断、边产出”的实现方式。

这里有一个很值得讲清楚的点：Claude Code 的流式，不是很多人想象中的“逐字打印”。它更接近一种“按消息块、按事件块”的流式。

也就是说，系统不是每生成一个字就立刻往外吐一次，而是随着模型流中的事件推进，不断 yield message。

这个差别很重要，因为它直接影响你怎么理解 queryLoop。

5.1 为什么 yield message 就等于流式输出

理解 Claude Code 的流式，最好的方式不是只看一层代码，而是看它怎么“一层一层往外 yield”。

先看里面这一层，也就是 queryLoop。它一边跑 Agent Loop，一边把每轮里从模型拿到的消息往上抛：

// src/query.ts
async function* queryLoop(
  params: QueryParams,
): AsyncGenerator<StreamEvent | Message, Terminal> {
  while (true) {
    for await (const message of queryModel(
      state.messages,
      systemPrompt,
      tools,
      signal,
    )) {
      yield message;
    }

    // ---- 步骤 2: 检查是否需要继续 ----
    if (!needsFollowUp) {
      return { reason: 'end_turn' };
    }

    // ---- 步骤 3: 执行工具，收集结果 ----
    // ---- 步骤 4: 追加工具结果到消息列表 ----
    // ---- 步骤 5: 回到步骤 1 ----
    state.turnCount++;
  }
}

这说明第一层流式非常直接：queryModel() 持续产生消息，queryLoop() 就持续 yield message。所以对 queryLoop 来说，流式的本质就是“这轮里有什么消息到达，我就继续往上一层送什么消息”。

再看外面这一层，也就是 QueryEngine。它接收用户输入，把消息放进跨轮次保存的 mutableMessages，然后继续消费内部的 query()，再把内部消息流转成对外消息流：

// src/QueryEngine.ts
export class QueryEngine {
  // 跨轮次持久化的消息列表 —— 这就是教学版的 messages[]
  private mutableMessages: Message[]
  private abortController: AbortController
  private totalUsage: NonNullableUsage

  // 入口：用户输入进来，响应消息流出去
  async *submitMessage(
    prompt: string | ContentBlockParam[],
    options?: { uuid?: string; isMeta?: boolean },
  ): AsyncGenerator<SDKMessage, void, unknown> {
    // 1. 处理用户输入
    const { messages: messagesFromUserInput } = await processUserInput({...})
    this.mutableMessages.push(...messagesFromUserInput)

    // 2. 调用核心查询循环
    for await (const message of query({
      messages: [...this.mutableMessages],
      tools: this.tools,
      systemPrompt: this.systemPrompt,
      ...
    })) {
      // 3. 累积消息并持久化
      if (message.type === 'assistant') {
        this.mutableMessages.push(message)
        yield* normalizeMessage(message)
      }
    }
  }
}

这样一来，整条链路就清楚了：

1. queryModel() 先在最底层按事件产生消息；
2. queryLoop() 在每一轮里把这些消息 yield 出来；
3. QueryEngine.submitMessage() 再把内部消息流继续 yield 给外部。

所以 Claude Code 的“流式”本质上不是某一层单独在流，而是异步生成器在层层传递消息。

可以用一张图先把这条链路记住：

flowchart TD
    A["queryModel<br/>底层模型事件流"] --> B["queryLoop<br/>按轮次处理并 yield message"]
    B --> C["QueryEngine.submitMessage<br/>消费内部消息流并继续 yield"]
    C --> D["UI / SDK<br/>接收对外消息流"]

很多人以为“流式”就一定是 token 级别的逐字显示，但 Claude Code 这类 runtime 通常不会直接把最底层 token 流暴露给最外层逻辑。

原因是 runtime 真正要处理的，不只是文本，还有很多结构化信息：

• assistant message
• stream event
• tool use
• tool result
• progress
• status
• result

这些东西本身就不是“一个字一个字”的概念，而是分段、分块、分事件到达的。

所以更准确地说，Claude Code 的流式是：

• LLM 底层协议是更细粒度的事件流；
• 中间层把这些事件整理成可消费的消息块；
• queryLoop 再把这些消息块持续 yield 给外层。

这就是为什么你会感觉它是“一段一段出来”，而不是终端里那种纯文本逐字打印。

6. QueryEngine 是外层编排器，它不负责思考，但负责把循环组织起来

理解完 queryLoop 之后，再看 QueryEngine 会更清楚。

queryLoop 是发动机，但发动机本身并不负责整辆车的所有事情。Claude Code 还需要有一个更外层的组件，把会话、消息记录、结果聚合、状态同步这些事情组织起来，这就是 QueryEngine 这类角色存在的意义。

你可以把它理解成“外层编排器”。

它通常不直接决定模型这一轮该不该调工具，也不直接决定工具参数是什么。那些都是 loop 内部和模型共同完成的事情。QueryEngine 更关心的是：

• 这次查询从哪里开始；
• 初始消息怎么组装；
• 流式过程中哪些消息要记录；
• 哪些中间消息要回放给 UI 或 SDK；
• 本轮结束后，最终结果应该如何包装返回；
• 会话级别的 usage、cost、turn count 如何累计。

这件事在源码里也非常直观。QueryEngine 一开始维护的就是一批会话级状态：

// QueryEngine.ts
export class QueryEngine {
  private mutableMessages: Message[];
  private abortController: AbortController;
  private permissionDenials: SDKPermissionDenial[];
  private totalUsage: NonNullableUsage;
  private readFileState: FileStateCache;
}

进入一次查询之后，它会继续跟踪这次会话的关键统计：

// QueryEngine.ts
let currentMessageUsage: NonNullableUsage = EMPTY_USAGE
let turnCount = 1
let lastStopReason: string | null = null

for await (const message of query({ ... })) {
  // 消费 query() 产出的消息，并累计 usage / turn / stop_reason
}

最后再把这些状态收束成对外返回的 result：

// QueryEngine.ts
yield {
  type: 'result',
  subtype: 'error_max_budget_usd',
  duration_ms: Date.now() - startTime,
  num_turns: turnCount,
  stop_reason: lastStopReason,
  total_cost_usd: getTotalCost(),
  usage: this.totalUsage,
}

这里虽然展示的是一个具体错误分支，但它已经足够说明 QueryEngine 的职责：
它负责把 loop 过程中分散产生的状态，最后整理成一个完整、统一、可返回的结果对象。

也就是说，QueryEngine 解决的是“这一整次交互怎么被托管”，而 queryLoop 解决的是“这一轮又一轮怎么往前跑”。

6.1 为什么要有这一层

如果没有 QueryEngine 这一层，很多原本应该属于“会话级”的工作，就会被硬塞进 loop 里，比如：

• transcript 持久化；
• 历史消息回放；
• result 聚合；
• session 级别统计；
• UI/SDK 的输出适配。

这样一来，queryLoop 会越来越胖，最后既要管控制流，又要管存储，又要管展示，维护成本会非常高。

把 QueryEngine 单独拉出来之后，职责边界就清楚了：

• QueryEngine 负责托管整次查询；
• queryLoop 负责推进 agent 回合；
• 更底层的 model adapter 负责协议流；
• 工具执行器负责工具生命周期。

这正是前面提到的“隔离变化”的具体体现。

7. 结语

如果只用一句话总结这篇文章，我会说：Claude Code 的 Agent Loop，本质上是一套围绕“消息流”组织起来的运行时。

前面几节其实都在说明这件事，只是从不同层次切进去：

• 在第 4 节里，我们看到一个回合并不是“没工具了就退出”，而是会先尝试恢复，恢复不了才真正结束；
• 在第 5 节里，我们看到所谓流式输出，并不是单层函数在打印文本，而是 queryLoop 和 QueryEngine 两层异步生成器在层层 yield；
• 在第 6 节里，我们又看到 QueryEngine 如何把这些分散的中间状态组织成一整次可托管、可返回的查询过程。

把这些点连起来看，Claude Code 其实回答了一个很实际的问题：

一个 agent 为什么能持续跑下去，而且还能在复杂情况下不轻易跑崩？

答案不是“它 prompt 写得更好”，而是它把消息、回合、恢复和对外输出组织成了一套清晰的 runtime 结构。

所以读完这篇文章之后，最值得带走的并不是某个具体函数名，而是这条主线：

1. queryLoop 负责把一轮一轮的 agent 行为跑起来；
2. QueryEngine 负责把这套循环托管成一次完整交互；
3. 整个系统通过消息流把模型输出、工具结果和最终结果串成同一条链路。

当你理解了这一点，再回头看 Claude Code，就会发现它真正厉害的地方，不是“会调用工具”，而是它把 agent 的执行过程做成了一个稳定、连续、可恢复的运行时。

Claude Code 的源码泄漏之后，发现它的核心交互界面 src/screens/REPL.tsx 居然有 5005 行。一个文件。一个函数组件。

好奇心驱动我通读了一遍。约 290 个 import，60+ 个 useState，30+ 个 useEffect，20+ 个 useCallback。这个组件跑在 Ink（React 的终端渲染器）上面，承载了 Claude Code CLI 几乎所有的交互逻辑。

读完之后感触很复杂——有些地方写得确实漂亮，有些地方你能感觉到是被 deadline 推着走的妥协。记录一下。

---

这个文件干什么用的

REPL 就是 Read-Eval-Print Loop。打开终端敲 claude，你看到的整个界面就是这个组件在渲染。它负责：

• 接收你的输入（文字、斜杠命令、粘贴的图片、语音）
• 跟 Claude API 通信（流式响应、工具调用、中断）
• 画出终端界面（消息列表、等待动画、权限弹窗、搜索）
• 协调多种运行模式（本地、远程 WebSocket、SSH、Direct Connect、Swarm 多 agent 协作）
• 管理会话（创建、恢复、fork、丢到后台、退出）

技术栈是 React 19 + React Compiler + Ink + TypeScript，构建工具是 Bun。

---

写得漂亮的地方

编译期条件导入

const useVoiceIntegration = feature('VOICE_MODE')
  ? require('../hooks/useVoiceIntegration.js').useVoiceIntegration
  : () => ({ stripTrailing: () => 0, handleKeyEvent: () => {}, resetAnchor: () => {} });

feature() 是 Bun 的编译期常量。构建的时候，没开的功能连 require 那一行都会被消除掉，包括它引入的整个模块依赖树。

妙在 stub 的设计。给了个返回空操作的函数，而不是 null。这样后面 useVoiceIntegration() 该调用照调用，不用到处写 if (feature('VOICE_MODE')) 守卫，Hook 调用顺序也不会乱。用 typeof import(...) 约束 stub 签名和真实实现一致，类型层面就堵住了不匹配的口。

整个文件有十几处这种模式，涵盖语音输入、挫折检测、组织告警、Coordinator 模式等内部功能。外部发布版本的产物里，这些代码物理上就不存在。比运行时 flag 判断干净太多了。

QueryGuard 并发状态机

const queryGuard = React.useRef(new QueryGuard()).current;
const isQueryActive = React.useSyncExternalStore(queryGuard.subscribe, queryGuard.getSnapshot);

大部分 React 应用处理"是否在加载"就是一个 useState(false)。但 Claude Code 面对的场景比普通应用复杂——用户可以快速按 Enter 提交、Esc 取消、再按 Enter 重新提交，中间还可能有后台 agent 的通知触发新查询。

传统的 useState + useRef 双写模式在这种场景下很容易翻车，因为 React 的 setState 是异步批处理的，ref 和 state 之间会出现时间窗口不一致。

QueryGuard 把这个问题建模成了一个状态机，四个原子操作（reserve / tryStart / end / forceEnd），加一个 generation 计数器。当用户按 Esc 取消再立即重新提交时，旧查询的 finally block 里拿到的 generation 跟当前不匹配，就知道自己已经过时了，不会去清理新查询的状态。

通过 useSyncExternalStore 暴露给 React，不需要手动 setState，订阅者自动感知变化。这是正确处理这类问题的方式，但说实话在业界能看到这种做法的项目不多。

同步 Ref 镜像——"Zustand 模式"

const setMessages = useCallback((action) => {
  const prev = messagesRef.current;
  const next = typeof action === 'function' ? action(messagesRef.current) : action;
  messagesRef.current = next;  // 同步写 ref
  rawSetMessages(next);         // 异步通知 React
}, []);

React 的 setState 是异步的，但很多回调需要同步读到最新值。常规做法是 useEffect 里同步 ref，但会有一帧延迟。

Claude Code 直接在 setState 的包装器里先写 ref，再把算好的结果（注意不是 updater 函数）传给真正的 rawSetMessages。代码注释里管这叫"Zustand 模式"——ref 是 source of truth，React state 是它的渲染投影。

这个模式在文件里被反复使用：messagesRef、inputValueRef、streamModeRef、abortControllerRef、focusedInputDialogRef... 大概有七八处。如果你的 React 应用也有"异步回调里读状态总是旧的"这个痛点，这是目前最实用的解法。

细致的性能管理

这个文件里的性能优化不是那种"加个 memo 完事"的程度，而是对 React 渲染模型有系统性理解后做的：

动画隔离：终端标题有个 960ms 一跳的动画前缀（⠂ / ⠐ 交替）。如果把 setInterval 放在 REPL 主组件里，每秒就多一次整棵树的 re-render。所以他们提取了一个 AnimatedTerminalTitle 组件，返回 null（纯副作用），tick 只触发这个空组件的 re-render。

Ref 替代频繁变化的 State：streamMode 在流式响应期间大概切换 10 次（requesting → responding → tool-use 循环）。如果把它放进 onSubmit 的依赖数组，每次切换都重建 onSubmit → PromptInput props 变化 → 整个输入区域 re-render。解法是用 ref 镜像，回调通过 ref 读，React 渲染不感知这个变化。

双流渲染：useDeferredValue(messages) 产生一个延迟版本的消息列表。流式响应期间，Spinner 和输入框用实时的 messages，消息列表用延迟的 deferredMessages，这样长列表的 reconciliation 不会卡住输入。但当流式文本正在显示或查询结束时，又切回实时消息，避免"动画停了但回复还没出来"的闪烁。

const usesSyncMessages = showStreamingText || !isLoading;
const displayedMessages = usesSyncMessages ? messages : deferredMessages;

这种条件切换的思路比无脑 useDeferredValue 精细不少。

注释质量

我读过不少开源项目的代码，这个文件的注释水平是第一梯队的。不是"设置 loading 为 true"这种废话注释，而是记录"为什么"和"不这样做会怎样"：

// Josh Rosen's workflow: Claude emits long output → scroll
// up to read the start → start typing → before this fix, snapped to bottom.
// https://anthropic.slack.com/archives/C07VBSHV7EV/p1773545449871739
const RECENT_SCROLL_REPIN_WINDOW_MS = 3000;

一个常量附带了：具体的用户场景（谁遇到了什么问题）、修复前的行为、内部讨论链接。半年后新人看到这段代码，不用猜为什么是 3 秒。

另一个：

// Without this, paths that queue functional updaters then
// synchronously read the ref (e.g. handleSpeculationAccept →
// onQuery) see stale data.

直接告诉你：不加这行，具体哪个调用链会读到脏数据。这种注释的信息密度比代码本身还高。

中断后自动恢复

用户按 Esc 中断 Claude 的回复时，如果 Claude 还没产生什么有用的内容，REPL 会自动回退对话、恢复你之前输入的文字，省去重新打字的麻烦。

实现上卡了 5 个条件：中断原因必须是用户主动取消（不是程序性中断）、没有新查询在跑、输入框是空的（不覆盖用户已经开始打的新内容）、命令队列是空的、不在看 teammate 的视图。

这种细节不是架构层面的东西，但直接影响日常使用的手感。能把这种 edge case 一个个堵住，说明有大量真实使用反馈在驱动。

Idle-Return 提示

用户离开超过 75 分钟、对话已消耗超过 10 万 token 时，下次输入会提示"要不要 /clear 开个新对话"。

长对话的 KV cache 已经冷了，继续追加 token 成本高、响应质量也可能下降。但这个提示不是硬拦——支持阻断式弹窗和非阻断式通知两种形态，通过 A/B 测试（GrowthBook）切换，用户还能永久关掉。把成本优化做成了用户体验优化，不让人觉得"系统在限制我"。

---

问题

God Component

这是最大的问题，没有之一。

REPL 函数从第 572 行开始，到第 5004 行 return。中间塞了：

• 会话管理状态（messages, conversationId, sessionTitle）
• UI 状态（screen, showAllInTranscript, dumpMode, editorStatus）
• 输入状态（inputValue, inputMode, pastedContents, vimMode）
• 加载状态（queryGuard, isExternalLoading, streamMode, streamingToolUses）
• 弹窗队列（toolUseConfirmQueue, promptQueue, sandboxPermissionRequestQueue）
• 10+ 种 focusedInputDialog 类型

getFocusedInputDialog 函数（第 2017 行）是一个 30 多行的 if-else 优先级链，决定当多个弹窗同时需要显示时哪个获得焦点：

exit > message-selector > (输入抑制) > sandbox-permission >
tool-permission > prompt > worker-sandbox > elicitation > cost >
idle-return > ultraplan > ide-onboarding > model-switch > ...

本质上是在手动实现状态机，但没有用状态机来表达。新增一个弹窗类型时，必须准确地插在这条链的正确位置。

为什么不拆？我猜有几个原因：60+ 个 useState 里大约 40 个被两个以上的回调共享，拆出去就要大量 props drilling 或 context；onSubmit → onQuery → getToolUseContext 的回调依赖链很深，跨组件传递会更乱；React Compiler 对大组件做了细粒度缓存，性能惩罚没有传统 React 那么大。

但更可能的真相是：没有人设计了一个 5000 行的组件。它是随功能迭代长出来的。每次加个新功能（voice、swarm、ultraplan、companion sprite），在现有 REPL 里加几个 useState 和一段 JSX 是最快的迭代方式。直到有一天发现已经 5000 行了。

回调依赖爆炸

onSubmit（第 3142 行）的依赖数组有 30 多项。这意味着其中任何一个值变化，整个回调都会重建，进而导致 PromptInput 的 props 变化和下游的级联 re-render。

为了缓解这个问题，文件里造了大量 ref 镜像（onSubmitRef、streamModeRef、terminalFocusRef 等），让回调通过 ref 读取而不是闭包捕获。

这本身就是一个信号——当你需要 10 个 ref 来保持一个回调稳定，说明这个回调承担了太多职责。

resume 函数

resume 回调（第 1735 行）有 213 行，执行 20 多个步骤：反序列化消息 → 匹配 coordinator 模式 → 执行 SessionEnd hooks → 执行 SessionStart hooks → 复制 plan → 恢复 file history → 恢复 agent 设置 → 恢复 cost state → 切换 session → 重命名 asciicast → 重置 session file pointer → 清除/恢复 session metadata → 退出/恢复 worktree → 恢复 content replacement → 重置 messages → 清除 input...

这个函数应该是一个独立模块。但它依赖了 REPL 的大量局部状态（readFileState、haikuTitleAttemptedRef、bashTools），想提取出去很困难。这就是 God Component 的典型症状——所有东西都耦合在一起，想拆任何一块都牵一发动全身。

条件 Hook

if (feature('AWAY_SUMMARY')) {
  // biome-ignore lint/correctness/useHookAtTopLevel: feature() is a compile-time constant
  useAwaySummary(messages, setMessages, isLoading);
}

整个文件有 10 多处这种条件 Hook 调用。feature() 是编译期常量没错，运行时不会变，不会违反 Hook 规则。但这依赖 Bun 的 DCE 正确工作，TypeScript Server 不认识这是常量（标红要 suppress），每个 code review 都要人肉确认"这真的是编译期常量"。

更稳的做法是把条件 Hook 提取为独立组件，用条件渲染代替条件调用：

{feature('AWAY_SUMMARY') && <AwaySummaryProvider messages={messages} ... />}

JSX 的可读性

mainReturn（第 4548 行开始）是一棵巨大的 JSX 树。15 个以上的弹窗组件嵌在里面，每个的 onDone / onResponse 回调直接内联，最长的 onSummarize 有 40 多行。

{focusedInputDialog === 'idle-return' && idleReturnPending &&
  <IdleReturnDialog
    idleMinutes={idleReturnPending.idleMinutes}
    totalInputTokens={getTotalInputTokens()}
    onDone={async action => {
      // 40 行回调逻辑...
    }}
  />}

布局结构被回调逻辑淹没了。改任何一个弹窗的回调，git diff 看起来像改了整个渲染树。想单独测试某个弹窗的行为？不可能，它跟 REPL 的 5000 行状态绑死了。

Magic Numbers 分散

const RECENT_SCROLL_REPIN_WINDOW_MS = 3000;
const PROMPT_SUPPRESSION_MS = 1500;
if (turnDurationMs > 30000 || budgetInfo !== undefined) { ... }
if (count >= 3) return; // autoPermissionsNotificationCount
if (wt.creationDurationMs < 15_000) return; // worktree tip threshold

大部分有命名或注释，但散落在 5000 行的各个角落。想调一个阈值，得先找到它在哪。

错误处理不统一

文件里混用了三种异步错误处理模式：

1. void someAsyncCall().then(...).catch(...) — 约 20 处
2. try { await ... } catch { ... } — 约 15 处
3. void someAsyncCall() 不处理 — 约 5 处

没有统一的策略。某些路径的静默失败可能在极端场景下产生莫名其妙的 bug。

Feature Flag 爆炸

文件里用了 17 个 feature flag：

VOICE_MODE, COORDINATOR_MODE, PROACTIVE, KAIROS, TOKEN_BUDGET,
BRIDGE_MODE, TRANSCRIPT_CLASSIFIER, BG_SESSIONS, MESSAGE_ACTIONS,
ULTRAPLAN, BUDDY, AWAY_SUMMARY, WEB_BROWSER_TOOL, HOOK_PROMPTS,
CONTEXT_COLLAPSE, COMMIT_ATTRIBUTION, AGENT_TRIGGERS

编译期消除保证了运行时不会慢，但源码层面，17 个 flag 理论上有 131,072 种代码路径组合。读代码时脑子里要不断过滤"这段在外部构建里存不存在"，心智负担不小。

---

几个有意思的设计细节

Telemetry 的类型约束

logEvent('tengu_session_resumed', {
  entrypoint: entrypoint as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
  success: true,
});

AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS 这个类型名是认真的。它强制每个埋点调用者通过 as 断言来确认"我检查过了，这个值里没有用户代码或文件路径"。Code review 时看到这个断言就知道要额外关注隐私合规。用类型系统来编码安全策略，思路很好。

统一的去重模式

文件里到处都是 ref 做的一次性守卫：

• tipPickedThisTurnRef：防止 resetLoadingState 执行两次时重复选 spinner tip
• hasCountedQueueUseRef：防止 saveGlobalConfig 的写风暴（并发会话下会打架）
• idleHintShownRef：每会话只显示一次 idle 提示
• safeYoloMessageShownRef：auto mode 提示最多显示 3 次

模式一样，但每次都手写。如果提取个 useOncePerTurn 或 useGuardedEffect 会干净很多。

远程模式的统一抽象

const activeRemote = sshRemote.isRemoteMode
  ? sshRemote
  : directConnect.isRemoteMode
    ? directConnect
    : remoteSession;

SSH、Direct Connect、WebSocket Remote 三种模式通过相同接口（sendMessage、cancelRequest、isRemoteMode）抽象。REPL 只跟 activeRemote 交互，不关心底下是什么传输层。没有远程模式时 isRemoteMode 为 false，所有远程代码路径自然跳过。简单有效。

AppState 和 Local State 的分界线

REPL 同时用了 Zustand 风格的全局 store（AppState）和组件内的 useState。分界线不太清晰：

状态	存储位置
messages	local useState
toolPermissionContext	AppState
streamMode	local useState
fileHistory	AppState
inputValue	local useState
viewingAgentTaskId	AppState

大致的规则好像是：需要被子 agent、后台任务、MCP handler 读取的放 AppState，纯 UI 状态放 local。但 messages 作为最核心的状态却是 local 的，通过回调传递给需要的地方。这导致 getToolUseContext 要同时从 store.getState() 和闭包里取数据，两个世界混在一起。

---

总结

维度	好的方面	不好的方面
规模	功能覆盖完整	单文件过大，认知负担重
性能	系统性优化，不是零敲碎打	部分优化是在弥补架构问题
可读性	注释质量极高	回调嵌套深，JSX 结构被淹没
可维护性	类型安全，编译期 flag 消除	60+ useState 想重构无从下手
错误处理	自动恢复、防御性守卫细致	三种模式混用，策略不统一

如果要给一个评价：这是技术功底很深的人在高速迭代压力下写出来的代码。

每一个 useState 都有存在的理由，每一个 useEffect 都解决了真实的问题，每一段注释都记录了一次 bug 修复或一个产品决策。但当 5000 行积累在一个函数里，整体的可维护性还是不可避免地下降了。

不过话说回来，这可能是工程中最常见也最现实的困境：不是代码写得不好，而是好代码在持续迭代中没有找到结构性重构的时机。写代码的人比谁都清楚这里该拆，但 5005 行的组件和 5005 行的 TODO 之间，前者至少能跑。

---

说到底，这个项目大概率是 Claude Code 自己迭代自己写出来的。用人类的代码审美去评判一个 AI 写给自己用的代码，多少有点错位。但至少读的过程中能学到不少东西。而且往远了想，也许以后大家真的不用手写代码了，代码只要 AI 自己能看懂就行——到那时候，可读性、可维护性这些标准可能得重新定义了。

基于 Claude Code v2.1.88 源码分析，仅供技术交流。

JavaScript中this绑定问题详解

问题描述

在JavaScript中，当在回调函数（如setTimeout）中使用this时，经常会出现this指向丢失的问题。本文档详细分析了这个问题及其解决方案。

示例代码分析

原始代码

var obj = {
    count: 0,
    cool: function coolFn() {
        var self = this;

        if (self.count < 1) {
            setTimeout(function timer() {
                self.count++;
                console.log('awesome?');
            }, 100);
        }
    }
}

obj.cool();

代码执行流程

1. 步骤1: 执行 obj.cool()，调用cool方法
2. 步骤2: 在cool方法内部，this指向obj对象，通过var self = this;保存这个引用
3. 步骤3: 条件判断 self.count < 1 为true（初始值为0）
4. 步骤4: 设置setTimeout定时器，延迟100ms执行
5. 步骤5: cool方法执行完毕
6. 步骤6: 100ms后定时器触发，执行回调函数
7. 步骤7: self.count++ 将count变为1，输出"awesome?"

var self = this 的工作原理

1. 调用时的this指向

当执行 obj.cool() 时，根据隐式绑定规则，函数内的this指向obj对象本身。

obj.cool();  // 此时cool函数内的this指向obj

2. 保存this引用

var self = this;

这行代码的作用：

• 将当前this（指向obj）的引用保存到局部变量self中
• self变量存储的是对obj对象的引用
• 通过闭包机制，这个引用在定时器回调函数中仍然可访问

3. 解决this丢失问题

如果没有保存this引用：

// ❌ 错误示例 - this指向丢失
setTimeout(function timer() {
    this.count++;  // this指向全局对象或undefined，不是obj
}, 100);

// ✅ 正确示例 - 使用self
setTimeout(function timer() {
    self.count++;  // self仍指向obj
}, 100);

闭包的作用

timer回调函数形成了闭包：

function coolFn() {
    var self = this;  // 外层函数作用域

    return function timer() {
        // 内层函数可以访问外层函数的self变量
        self.count++;
    };
}

闭包特性：

• 即使coolFn函数执行完毕，self变量仍然存在于内存中
• timer函数引用着self变量，所以不会被垃圾回收
• 定时器触发时，仍然可以访问到保存的self引用

三种解决this绑定问题的方法

方法1：使用箭头函数（推荐）

var obj = {
    count: 0,
    cool: function coolFn() {
        if (this.count < 1) {
            setTimeout(() => {
                // 箭头函数不改变this指向，this仍然指向obj
                this.count++;
                console.log('awesome?');
            }, 100);
        }
    }
}

obj.cool();

特点：

• 箭头函数没有自己的this，继承外层作用域的this
• 代码简洁优雅
• ES6语法，现代浏览器和Node.js都支持

方法2：使用bind绑定

var obj = {
    count: 0,
    cool: function coolFn() {
        if (this.count < 1) {
            setTimeout(function timer() {
                this.count++;
                console.log('awesome?');
            }.bind(this), 100);  // 使用bind将this绑定到当前函数的this
        }
    }
}

obj.cool();

特点：

• 使用Function.prototype.bind方法显式绑定this
• 代码稍长，但意图明确
• 兼容性较好（ES5）

方法3：使用var self = this（经典方案）

var obj = {
    count: 0,
    cool: function coolFn() {
        var self = this;  // 保存this引用

        if (this.count < 1) {
            setTimeout(function timer() {
                self.count++;  // 使用保存的引用
                console.log('awesome?');
            }, 100);
        }
    }
}

obj.cool();

特点：

• 经典解决方案，兼容性最好
• 适合需要支持旧版浏览器的场景
• 需要额外的变量声明

三种方法对比

方法	特点	代码简洁性	兼容性	推荐度
var self = this	经典方案，兼容性好	中	ES3	⭐⭐⭐
箭头函数	不改变this指向	高	ES6+	⭐⭐⭐⭐⭐
bind(this)	显式绑定	中	ES5	⭐⭐⭐⭐

在项目中的应用建议

推荐使用箭头函数方案，因为：

1. 代码更简洁优雅
2. 符合现代JavaScript开发习惯
3. TypeScript对箭头函数有良好支持
4. 提高代码可读性和维护性

补充：this指向规则总结

1. 默认绑定: 严格模式下指向undefined，非严格模式指向全局对象
2. 隐式绑定: 调用时使用对象，this指向该对象
3. 显式绑定: 使用call、apply、bind显式指定this
4. new绑定: 使用new调用构造函数，this指向新创建的对象
5. 箭头函数: 继承外层作用域的this，不能被改变

参考资源

• MDN - Arrow functions
• MDN - Function.prototype.bind
• You Don't Know JS - this & Object Prototypes

目录

1. 从现象出发：Claude Code 是什么？
2. 项目结构：模块化的插件仓库
3. 整体架构：可扩展的能力注册系统
4. 记忆系统：三层记忆架构
5. 上下文管理：动态压缩与快照
6. 通信协议：流式 API 与实时交互
7. UI 层：Ink 驱动的终端渲染
8. 核心模块一：Commands（命令系统）
9. 核心模块二：Agents（智能代理）
10. 核心模块三：Skills（技能系统）
11. 核心模块四：Hooks（钩子与治理）
12. MCP 协议：连接外部世界
13. 工具系统：执行引擎
14. 实战案例：Feature-Dev 插件剖析
15. CLI 使用方式与最佳实践
16. 总结：Markdown 驱动的 AI 应用新范式
17. 三足鼎立：Claude Code vs Codex vs Gemini CLI

---

1. 从现象出发：Claude Code 是什么？

1.1 大白话解释

如果说传统的 AI 编程助手（如 GitHub Copilot）是一个"智能的代码补全工具"，那么 Claude Code 就是一个住在你终端里的全职程序员。

它不仅能写代码，还能：

• 🔍 理解项目结构：自动分析代码库架构
• 🤖 自主执行任务：通过工具调用完成复杂操作（git commit、运行测试、创建 PR）
• 🧠 记住上下文：跨会话记住项目规范和待办事项
• 🔌 连接外部服务：通过 MCP 协议集成数据库、API 等外部资源
• 🛡️ 安全治理：通过 Hook 系统拦截危险操作

1.2 核心差异

特性	GitHub Copilot	Claude Code
交互模式	代码补全（被动）	对话式 + 自主执行（主动）
执行能力	无	可执行 Bash、读写文件、调用 API
记忆系统	无状态	项目级配置（CLAUDE.md）+ 会话历史
可扩展性	固定功能	插件系统，用户可自定义
安全机制	无	Hook 系统拦截 + 权限控制

1.3 应用场景

graph LR
    User[开发者] -->|"实现登录功能"| Claude[Claude Code]
    Claude -->|"1. 探索代码"| Explore[Code Explorer Agent]
    Claude -->|"2. 设计架构"| Architect[Code Architect Agent]
    Claude -->|"3. 编写代码"| Implement[实现模块]
    Claude -->|"4. 代码审查"| Review[Code Reviewer Agent]
    Claude -->|"5. 提交代码"| Git[Git 操作]

    style Claude fill:#f9f,stroke:#333,stroke-width:4px

---

2. 项目结构：模块化的插件仓库

2.1 目录树与功能划分

通过逆向分析 claude-code 项目，我们发现这是一个插件仓库而非核心引擎代码库。核心引擎是 Bun 编译的闭源 CLI 工具（源码可通过逆向提取到 extracted/src/），而这个仓库提供了 13+ 官方插件。核心引擎的源码包含 30+ 内置工具、插件加载器、Hook 执行引擎、MCP 客户端等完整实现。

claude-code/
├── .claude/                    # 根级别命令定义
│   └── commands/              # 全局 Slash 命令
│       ├── commit-push-pr.md  # Git 工作流
│       ├── oncall-triage.md   # Issue 分类
│       └── dedupe.md          # 重复检测
├── .claude-plugin/            # 插件市场配置
│   └── marketplace.json       # 13 个插件的注册清单
├── plugins/                   # 插件目录（核心）
│   ├── feature-dev/          # 功能开发工作流
│   ├── code-review/          # 代码审查
│   ├── hookify/              # 用户自定义规则引擎
│   ├── security-guidance/    # 安全警告
│   ├── plugin-dev/           # 插件开发工具包
│   └── ...                   # 其他 8 个插件
├── examples/                  # 示例配置
├── scripts/                   # 自动化脚本
└── doc/                       # 文档

2.2 插件类型分类

graph TB
    subgraph DevTools["🛠️ 开发工具插件 (4)"]
        FD[feature-dev<br/>7阶段功能开发]
        PD[plugin-dev<br/>插件脚手架]
        ASD[agent-sdk-dev<br/>SDK项目生成]
        MIG[claude-opus-4-5-migration<br/>模型迁移]
    end

    subgraph Productivity["⚡ 生产力插件 (3)"]
        CR[code-review<br/>自动PR审查]
        PRT[pr-review-toolkit<br/>6种专业审查]
        CC[commit-commands<br/>Git提交工作流]
    end

    subgraph Learning["📚 学习增强插件 (2)"]
        EO[explanatory-output-style<br/>教学模式]
        LO[learning-output-style<br/>互动学习]
    end

    subgraph Security["🔐 安全治理插件 (2)"]
        HF[hookify<br/>自定义行为规则]
        SG[security-guidance<br/>安全模式拦截]
    end

    subgraph Design["🎨 设计辅助插件 (1)"]
        FE[frontend-design<br/>UI/UX设计指导]
    end

    subgraph Other["🔮 其他插件 (1)"]
        RW[ralph-wiggum<br/>自引用迭代]
    end

    Core["🎯 Claude Code 核心引擎<br/>插件注册中心"]

    Core -.加载.-> DevTools
    Core -.加载.-> Productivity
    Core -.加载.-> Learning
    Core -.加载.-> Security
    Core -.加载.-> Design
    Core -.加载.-> Other

类别	插件名称	核心功能
开发工具	feature-dev	7 阶段功能开发工作流
	plugin-dev	插件开发脚手架
	agent-sdk-dev	Claude Agent SDK 项目生成
	claude-opus-4-5-migration	模型迁移工具
生产力	code-review	自动化 PR 审查
	pr-review-toolkit	6 种专业审查 Agent
	commit-commands	Git 提交工作流
学习增强	explanatory-output-style	教学模式
	learning-output-style	互动学习
安全治理	hookify	用户自定义行为规则
	security-guidance	安全模式拦截
设计辅助	frontend-design	UI/UX 设计指导
其他	ralph-wiggum	自引用迭代循环

---

3. 整体架构：可扩展的能力注册系统

3.1 架构分层

Claude Code 采用微内核 + 插件的架构模式。核心引擎负责：

• 🧠 LLM 交互（流式请求、上下文管理）
• 🔧 工具执行（Bash, Read, Write, Edit 等）
• 🔌 MCP 客户端（连接外部服务）
• 📦 插件加载器（动态发现和注册）

而业务逻辑全部由插件提供。

flowchart TB
    subgraph Layer1["🖥️ 用户交互层 - User Interface Layer"]
        direction LR
        CLI["💻 CLI 终端<br/><small>命令行交互</small>"]
        VSCode["📝 VSCode 扩展<br/><small>IDE 集成</small>"]
        GitHub["🤖 GitHub Bot<br/><small>CI/CD 自动化</small>"]
    end

    subgraph Layer2["⚙️ 核心引擎层 - Core Engine Layer <small>(闭源)</small>"]
        direction TB

        subgraph Router_Group["🎯 请求路由模块"]
            Router["Intent Router<br/><small>智能意图识别</small>"]
        end

        subgraph Context_Group["🧠 上下文管理模块"]
            Context["Context Manager<br/><small>记忆压缩·注入</small>"]
            PluginLoader["Plugin Loader<br/><small>动态插件发现</small>"]
        end

        subgraph Execution_Group["⚡ 执行引擎模块"]
            ToolEngine["Tool Execution Engine<br/><small>工具调用·沙箱隔离</small>"]
            MCPClient["MCP Client<br/><small>外部服务桥接</small>"]
        end
    end

    subgraph Layer3["🧩 插件生态层 - Plugin Ecosystem Layer <small>(开源)</small>"]
        direction TB

        Registry["📋 Capability Registry<br/><small>能力注册中心</small>"]

        subgraph Plugin_Types["插件能力矩阵"]
            direction LR
            Commands["⚡ Commands<br/><small>显式调用</small>"]
            Agents["🤖 Agents<br/><small>自主决策</small>"]
            Skills["📚 Skills<br/><small>隐式注入</small>"]
            Hooks["🪝 Hooks<br/><small>行为拦截</small>"]
        end
    end

    subgraph Layer4["🌐 外部服务层 - External Services Layer"]
        direction LR
        LLM["🧠 Claude API<br/><small>Sonnet 4.6/Opus 4.6/Haiku 4.5</small>"]
        MCP["🔌 MCP Servers<br/><small>GitHub·DB·FS</small>"]
        OS["💾 Operating System<br/><small>文件系统·Shell</small>"]
    end

    %% 交互层到核心层
    CLI ==>|stdin/stdout| Router
    VSCode ==>|MCP SDK Protocol| Router
    GitHub ==>|Webhooks| Router

    %% 核心层内部流转
    Router -->|分发请求| Context
    Router -->|触发加载| PluginLoader
    Context -.实时同步.-> PluginLoader

    PluginLoader ==>|注册能力| Registry

    %% 插件层到执行引擎
    Registry -->|路由| Plugin_Types
    Commands ==>|Tool Calls| ToolEngine
    Agents ==>|Tool Calls| ToolEngine
    Skills -.Prompt注入.-> Context
    Hooks -.拦截.-> ToolEngine

    %% 执行引擎到外部服务
    Context ==>|API 请求| LLM
    ToolEngine ==>|MCP 协议| MCPClient
    ToolEngine ==>|系统调用| OS
    MCPClient ==>|stdio/SSE/HTTP| MCP

3.2 插件发现与加载流程

核心引擎通过约定优于配置的方式自动发现插件。实际源码中并不存在独立的 "Capability Registry" 类或 "Intent Router" 类——插件的各组件（Commands、Agents、Skills、Hooks）分别由对应的加载器（loadPluginCommands、loadPluginAgents、loadSkillsDir、loadPluginHooks）加载后，通过 React hooks（useMergedCommands、useMergedTools）在 REPL 运行时合并到工具池和命令列表中：

sequenceDiagram
    participant Boot as 启动入口 (cli.tsx)
    participant Init as init()
    participant Loader as pluginLoader.ts
    participant FS as File System
    participant Hooks as useMergedTools/Commands

    Boot->>Init: 1. 初始化配置、认证、遥测
    Init->>Loader: 2. loadAllPlugins()
    Loader->>FS: 3. 读取 settings.json 中已安装插件列表

    loop 遍历每个已启用插件
        Loader->>FS: 4. 解析 plugin.json 清单
        Loader->>FS: 5. loadPluginCommands (commands/*.md)
        Loader->>FS: 6. loadPluginAgents (agents/*.md)
        Loader->>FS: 7. loadSkillsDir (skills/*/SKILL.md)
        Loader->>FS: 8. loadPluginHooks (hooks/hooks.json)
    end

    Loader-->>Hooks: 9. 插件组件注入到 REPL 运行时
    Hooks-->>Boot: 10. 合并到工具池 (assembleToolPool)

3.3 核心数据结构

// 实际源码中的插件元数据结构（src/types/plugin.ts + src/utils/plugins/schemas.ts）
// 通过 Zod Schema 验证
interface PluginManifest {
  name: string;              // 插件名称
  version?: string;          // 版本号（可选）
  description?: string;      // 描述
  author?: {                 // 作者信息
    name: string;
    email?: string;
  };
  mcpServers?: {             // MCP 服务器配置
    [serverName: string]: MCPServerConfig;
  };
}

// 实际加载结果类型（src/types/plugin.ts）
interface LoadedPlugin {
  name: string;
  dir: string;
  manifest: PluginManifest;
  components: PluginComponent[];       // 包含 commands, agents, skills, hooks
  source: {
    type: 'marketplace' | 'session' | 'builtin';
    marketplace?: string;
  };
}

// ⚠️ 注意：源码中没有独立的 "CapabilityRegistry" 类
// 插件组件加载后分别存入不同系统：
// - Commands/Skills → 通过 useMergedCommands() 合并到命令列表
// - Agents → 通过 loadPluginAgents() 注册到 AgentDefinitionsResult
// - Hooks → 通过 loadPluginHooks() 注入到 getAllHooks() 结果
// - Tools → 通过 useMergedTools() + assembleToolPool() 合并到工具池

---

4. 记忆系统：三层记忆架构

4.1 大白话解释

Claude Code 的记忆就像人脑一样分层存储：

• 🧬 长期记忆（硬盘）：用户全局偏好，永久保存
• 📚 中期记忆（项目文件）：项目规范和待办事项，跨会话持久化
• 💭 短期记忆（RAM）：当前对话历史，会话结束即清空

这种设计让 AI 既能记住你的编码习惯，又能适应每个项目的特殊规范。

4.2 三层记忆架构图

flowchart TB
    subgraph Disk["💾 持久化存储层 - Persistent Storage <small>(Disk)</small>"]
        direction TB

        L3["🌍 L3: Global Memory<br/><small>~/.claude/config.json</small><br/>📌 用户偏好 · API配置 · 模型设置"]

        subgraph ProjectLevel["📁 项目级存储"]
            direction LR
            L2["📜 L2-A: Project Constitution<br/><small>CLAUDE.md</small><br/>🎯 代码规范 · 架构原则"]
            L2T["✅ L2-B: Todo List<br/><small>.claude/todos.json</small><br/>📋 任务队列 · 断点续传"]
        end
    end

    subgraph RAM["⚡ 运行时内存层 - Runtime Memory <small>(RAM)</small>"]
        direction TB

        L1["🧬 L1: System Prompt<br/><small>核心身份定义</small><br/>🛠️ 工具定义 · Skill SOP · 安全策略"]

        L0["💭 L0: Session History<br/><small>对话上下文</small><br/>💬 用户消息 · AI响应 · 工具调用结果"]
    end

    subgraph Pipeline["🔄 上下文处理流水线 - Context Pipeline"]
        direction TB

        subgraph Injection["📥 注入阶段"]
            Injector["Prompt Injector<br/><small>多源上下文融合器</small>"]
        end

        subgraph Compression["📦 压缩阶段"]
            Monitor["Token Monitor<br/><small>Token 使用率监控</small><br/>⚠️ 90%阈值触发"]
            Compressor["Context Compressor<br/><small>智能压缩引擎</small><br/>📸 Summary + Snapshot"]
        end
    end

    FinalContext["🎯 Final Context<br/><small>最终上下文包</small><br/>📤 发送给 Claude API"]

    %% 数据流 - 持久化层到注入器
    L3 ==>|"① 用户偏好注入"| Injector
    L2 ==>|"② 项目规范注入"| Injector
    L2T ==>|"③ 待办事项注入"| Injector

    %% 数据流 - 运行时层
    L1 ==>|"④ 系统提示词（基座）"| Injector
    L0 -->|"⑤ 实时监控"| Monitor

    %% 压缩流程
    Monitor -.->|"超过90%"| Compressor
    Compressor ==>|"压缩结果"| L0
    L0 ==>|"⑥ 历史对话"| Injector

    %% 最终输出
    Injector ==>|"⑦ 组装完成"| FinalContext

4.3 记忆层级详解

L3: Global Memory（全局偏好）

存储位置：

• ~/.claude/CLAUDE.md：全局记忆文档（Markdown 格式，跨项目指令）
• ~/.claude/settings.json：配置文件（JSON 格式，模型、权限规则等）

作用：跨项目的通用配置和全局指令。CLAUDE.md 类似 Shell 的 .bashrc，而 settings.json 管理结构化配置。

// ~/.claude/settings.json 结构示例
{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": ["Bash(git *)"],
    "deny": []
  },
  "hooks": {
    "PreToolUse": [...]
  },
  "plugins": {
    "code-review@claude-code-marketplace": { "enabled": true }
  }
}

<!-- ~/.claude/CLAUDE.md 示例 -->
# 全局偏好
- 使用中文回复
- 代码风格：简洁
- 提交信息遵循 Conventional Commits

生命周期：永久存储。CLAUDE.md 通过 loadMemoryPrompt() 在每次 API 请求时注入 System Prompt；settings.json 通过 enableConfigs() 在启动时加载。

L2: Project Memory（项目规范）

存储位置：

• CLAUDE.md：项目规范文档
• .claude/todos.json：待办事项队列

CLAUDE.md 示例：

# 项目规范：MyApp

## 代码风格
- TypeScript 严格模式
- 使用 Prettier + ESLint
- 组件命名：PascalCase

## 架构原则
- 每个组件单一职责
- 所有函数必须有类型定义
- 错误使用 Result 类型而非异常

## 禁止操作
- ❌ 不要使用 `any` 类型
- ❌ 不要直接修改 package.json
- ❌ 不要提交 .env 文件

## Git 规范
遵循 Conventional Commits：
- feat: 新功能
- fix: Bug 修复
- docs: 文档更新

todos.json 示例：

{
  "version": 1,
  "todos": [
    {
      "content": "实现用户登录功能",
      "status": "in_progress",
      "activeForm": "实现用户登录功能",
      "createdAt": "2026-01-11T10:00:00Z"
    },
    {
      "content": "编写单元测试",
      "status": "pending",
      "activeForm": "编写单元测试",
      "createdAt": "2026-01-11T10:01:00Z"
    }
  ]
}

作用：这是项目的"宪法"，AI 必须遵守这些规则。每次会话启动时重新读取。

L1 & L0: Session Memory（会话记忆）

存储位置：内存中的消息数组

数据结构：

// 实际源码中的消息类型（src/types/message.ts）
// 注意：不使用简单的 role 字段，而是使用 discriminated union
type Message =
  | UserMessage           // 用户输入 + 工具结果
  | AssistantMessage      // LLM 响应（文本 + 工具调用）
  | ProgressMessage       // 工具执行进度（Hook进度等）
  | AttachmentMessage     // 附件（记忆注入、Hook结果）
  | SystemMessage         // 系统消息（本地命令输出等）
  | ToolUseSummaryMessage // 工具使用摘要
  | TombstoneMessage      // 已删除消息占位

// AssistantMessage 的核心结构
interface AssistantMessage {
  type: 'assistant';
  uuid: string;
  message: {
    content: Array<TextBlock | ToolUseBlock>;  // 可同时包含文本和工具调用
    stop_reason: 'end_turn' | 'tool_use' | 'max_tokens';
  };
  costUsd: number;
  durationMs: number;
}

// UserMessage 承载用户输入和工具结果
interface UserMessage {
  type: 'user';
  uuid: string;
  message: {
    content: Array<TextBlock | ToolResultBlock>;
  };
}

生命周期：仅在当前 CLI 进程存活。消息数组存储在 ToolUseContext.messages 中，一旦 Token 超限（90% 阈值），触发自动压缩机制（autoCompact）。

4.4 上下文组装逻辑

核心引擎在每次调用 Claude API 前，通过 getSystemPrompt() 和 query() 函数组装完整上下文：

// 实际源码逻辑（src/constants/prompts.ts + src/query.ts 精简）
async function getSystemPrompt(tools: Tools, model: string): Promise<SystemPrompt> {
  const sections: SystemPromptSection[] = [];

  // 1. 核心身份（模型名称、版本、能力说明）
  sections.push(systemPromptSection('core_identity', getCoreIdentity(model)));

  // 2. 工具定义（30+ 工具的 prompt 文本）
  for (const tool of tools) {
    sections.push(systemPromptSection(`tool_${tool.name}`, await tool.prompt(ctx)));
  }

  // 3. Skill 元数据（名称 + 描述，供 LLM 判断是否调用）
  const skills = getSkillToolCommands(commands);
  if (skills.length > 0) {
    sections.push(systemPromptSection('skills', buildSkillSection(skills)));
  }

  // 4. 安全规则
  sections.push(systemPromptSection('security', CYBER_RISK_INSTRUCTION));

  // 5. 输出样式（如果安装了 output-style 插件）
  const outputStyle = getOutputStyleConfig();
  if (outputStyle) {
    sections.push(systemPromptSection('output_style', outputStyle.instructions));
  }

  // 6. MCP 服务器指令
  for (const client of mcpClients) {
    if (client.instructions) {
      sections.push(systemPromptSection(`mcp_${client.name}`, client.instructions));
    }
  }

  return resolveSystemPromptSections(sections);
}

// CLAUDE.md 通过 loadMemoryPrompt() 在 query() 中作为 attachment 注入
// 不是作为 system message，而是通过 AttachmentMessage 机制
async function loadMemoryPrompt(): Promise<string | null> {
  const parts: string[] = [];
  // 1. ~/.claude/CLAUDE.md（全局）
  // 2. ./CLAUDE.md（项目）
  // 3. 向上遍历到 $HOME 的所有 CLAUDE.md
  return parts.join('\n\n');
}

纠正：原文描述将 CLAUDE.md 作为 <project_rules> 标签注入 system message。实际源码中，CLAUDE.md 的内容通过 loadMemoryPrompt()（位于 src/memdir/memdir.ts）加载，并作为 AttachmentMessage 附加到消息列表中，由 query() 在 normalizeMessagesForAPI() 时合并。

4.5 核心洞察

Claude Code 的"记忆"是一种错觉

它并没有真正的数据库，而是通过每次请求前疯狂读取文件并塞入 System Prompt，来模拟一个"记得项目背景"的 AI。这种 Stateless to Stateful 的转换技巧，是其架构的精髓。

优势：

• ✅ 简单：无需维护数据库
• ✅ 透明：记忆内容就是文件内容
• ✅ 可控：用户可直接编辑 CLAUDE.md

劣势：

• ⚠️ 每次启动都要重新读取
• ⚠️ 无法存储超大历史记录
• ⚠️ 依赖文件系统

---

5. 上下文管理：动态压缩与快照

5.1 为什么需要上下文压缩？

LLM 的 Context Window 是稀缺资源。Claude Sonnet 4.6 的默认上下文为 200K tokens（1M context 版本可扩展到 1M），看似很多，但在实际开发中：

一次完整的功能开发对话可能消耗：
- System Prompt: 5K tokens
- CLAUDE.md: 2K tokens
- 代码文件读取: 20K tokens
- 工具调用结果: 10K tokens
- 对话历史: 每轮 2-5K tokens

假设 30 轮对话 = 5K + 2K + 20K + 10K + (30 × 3K) = 127K tokens

当超过 **90% 阈值（180K tokens）**时，必须压缩，否则下一轮对话会失败。

5.2 压缩策略流程图

sequenceDiagram
    participant Engine as 核心引擎
    participant Monitor as Token 监控器
    participant LLM as Claude API
    participant Compressor as 压缩器

    Engine->>Monitor: 1. 每轮对话后检查 Token 使用
    Monitor->>Monitor: 2. 计算当前 Token 占用

    alt Token < 90%
        Monitor-->>Engine: 继续正常对话
    else Token >= 90%
        Monitor->>Compressor: 3. 触发压缩流程

        Compressor->>LLM: 4. 调用 LLM 生成对话摘要
        Note over Compressor,LLM: Prompt: "总结之前的对话，<br/>保留关键信息和决策"
        LLM-->>Compressor: 5. 返回摘要（Summary）

        Compressor->>Compressor: 6. 生成环境快照（Snapshot）<br/>- Git 状态<br/>- 文件树<br/>- 待办事项

        Compressor->>Compressor: 7. 丢弃旧对话历史<br/>保留最近 5 轮

        Compressor->>Engine: 8. 重构 Context:<br/>[Summary] + [Snapshot] + [Recent 5]

        Engine->>Monitor: 9. 重置 Token 计数器
        Monitor-->>Engine: 继续对话
    end

5.3 压缩器核心实现

// [伪代码] Context Compressor
class ContextCompressor {
  private readonly THRESHOLD = 0.9; // 90% 阈值
  private readonly CONTEXT_LIMIT = 200000; // 200K tokens
  private readonly KEEP_RECENT = 5; // 保留最近 5 轮对话

  // 检查是否需要压缩
  async checkAndCompress(history: Message[]): Promise<Message[]> {
    const currentTokens = this.estimateTokens(history);

    if (currentTokens < this.CONTEXT_LIMIT * this.THRESHOLD) {
      return history; // 无需压缩
    }

    console.log(`Token 使用达到 ${(currentTokens / this.CONTEXT_LIMIT * 100).toFixed(1)}%，触发压缩...`);

    // 1. 生成对话摘要
    const summary = await this.generateSummary(history);

    // 2. 生成环境快照
    const snapshot = await this.generateSnapshot();

    // 3. 保留最近的对话
    const recentMessages = history.slice(-this.KEEP_RECENT * 2); // 每轮包含 user + assistant

    // 4. 重构上下文
    return [
      {
        role: 'system',
        content: `<conversation_summary>\n${summary}\n</conversation_summary>`
      },
      {
        role: 'system',
        content: `<environment_snapshot>\n${snapshot}\n</environment_snapshot>`
      },
      ...recentMessages
    ];
  }

  // 生成对话摘要（调用 LLM）
  private async generateSummary(history: Message[]): Promise<string> {
    const summaryPrompt = `
请总结之前的对话内容，保留以下关键信息：
1. 用户的核心需求和目标
2. 已经完成的工作和决策
3. 遇到的问题和解决方案
4. 待完成的任务

保持简洁，突出重点。

<previous_conversation>
${this.formatHistoryForSummary(history)}
</previous_conversation>
    `;

    const response = await this.llm.chat([
      { role: 'user', content: summaryPrompt }
    ], {
      model: 'haiku', // 使用 Haiku 降低成本
      maxTokens: 2000
    });

    return response.content;
  }

  // 生成环境快照
  private async generateSnapshot(): Promise<string> {
    const parts: string[] = [];

    // Git 状态
    try {
      const gitStatus = await exec('git status --short');
      const gitBranch = await exec('git branch --show-current');
      parts.push(`## Git 状态\n分支：${gitBranch}\n变更：\n${gitStatus}`);
    } catch (e) {
      // 非 Git 项目
    }

    // 文件树（简化）
    try {
      const tree = await exec('tree -L 2 -I "node_modules|.git"');
      parts.push(`## 项目结构\n${tree}`);
    } catch (e) {
      // tree 命令不存在
    }

    // 待办事项
    const todos = await loadTodos('.claude/todos.json');
    if (todos.length > 0) {
      const todoList = todos.map((t, i) =>
        `${i + 1}. [${t.status}] ${t.content}`
      ).join('\n');
      parts.push(`## 待办事项\n${todoList}`);
    }

    return parts.join('\n\n');
  }

  // 估算 Token 数量（简化版）
  private estimateTokens(messages: Message[]): number {
    let total = 0;
    for (const msg of messages) {
      const content = typeof msg.content === 'string'
        ? msg.content
        : JSON.stringify(msg.content);
      // 粗略估算：1 token ≈ 4 字符
      total += Math.ceil(content.length / 4);
    }
    return total;
  }
}

5.4 压缩前后对比

压缩前（180K tokens）：

[System Prompt: 5K]
[CLAUDE.md: 2K]
[Todos: 1K]
[第1轮对话: 3K]
[第2轮对话: 4K]
...
[第30轮对话: 5K]
总计：~180K tokens

压缩后（40K tokens）：

[System Prompt: 5K]
[CLAUDE.md: 2K]
[Todos: 1K]
[对话摘要: 2K]          ← 替代前 25 轮对话
[环境快照: 3K]          ← Git/文件树/待办
[第26轮对话: 3K]        ← 保留最近 5 轮
[第27轮对话: 4K]
[第28轮对话: 3K]
[第29轮对话: 5K]
[第30轮对话: 5K]
总计：~40K tokens

压缩比：77.8%（节省 140K tokens）

5.5 用户触发的手动压缩

用户可以通过 /compact 命令手动触发压缩：

# 感觉 AI 反应变慢或开始产生幻觉时
/compact

这会强制执行压缩流程，让 AI"清醒"过来。

---

6. 通信协议：流式 API 与实时交互

6.1 为什么使用流式 API？

传统的 Request-Response 模式会让用户等待很久才看到结果，而流式 API可以边生成边显示：

传统模式：
用户提问 → [等待 10 秒] → 完整回答一次性显示

流式模式：
用户提问 → [0.5秒] → "我" → [0.5秒] → "会" → [0.5秒] → "帮" → ...

6.2 通信流程图

sequenceDiagram
    participant User as 用户输入
    participant CLI as CLI 主进程
    participant API as Claude API
    participant UI as UI 渲染器

    User->>CLI: 1. 输入问题
    CLI->>CLI: 2. 构建 Context
    CLI->>API: 3. POST /v1/messages<br/>stream=true

    loop 流式返回
        API-->>CLI: 4. SSE chunk: text
        CLI->>UI: 5. 更新显示
        UI-->>User: 实时渲染文本

        API-->>CLI: 6. SSE chunk: tool_use
        CLI->>UI: 7. 显示 "正在执行工具..."

        CLI->>CLI: 8. 执行工具调用
        CLI->>API: 9. 继续对话（附带结果）

        API-->>CLI: 10. SSE chunk: more text
        CLI->>UI: 11. 继续渲染
    end

    API-->>CLI: 12. SSE: stop_reason=end_turn
    CLI->>UI: 13. 对话完成

6.3 流式 API 调用实现

// [伪代码] Streaming API Client
class ClaudeStreamClient {
  async chat(
    messages: Message[],
    options: {
      model?: string;
      maxTokens?: number;
      onChunk?: (chunk: StreamChunk) => void;
    }
  ): Promise<string> {
    const response = await fetch('https://api.anthropic.com/v1/messages', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': this.apiKey,
        'anthropic-version': '2023-06-01',
        // 注意：CLI 不使用 anthropic-dangerous-direct-browser-access 头
      },
      body: JSON.stringify({
        model: options.model || 'claude-sonnet-4-6-20250514',
        max_tokens: options.maxTokens || 8192,
        messages,
        stream: true, // 关键：启用流式
        tools: this.getToolDefinitions() // 工具定义
      })
    });

    const reader = response.body.getReader();
    const decoder = new TextDecoder();
    let fullText = '';
    let buffer = '';

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      // 解析 SSE 格式
      buffer += decoder.decode(value, { stream: true });
      const lines = buffer.split('\n');
      buffer = lines.pop() || ''; // 保留不完整的行

      for (const line of lines) {
        if (line.startsWith('data: ')) {
          const data = line.slice(6);
          if (data === '[DONE]') continue;

          try {
            const chunk = JSON.parse(data);

            // 处理不同类型的 chunk
            switch (chunk.type) {
              case 'content_block_start':
                // 新的内容块开始
                if (chunk.content_block.type === 'text') {
                  // 文本块
                } else if (chunk.content_block.type === 'tool_use') {
                  // 工具调用块
                  options.onChunk?.({
                    type: 'tool_use_start',
                    toolName: chunk.content_block.name
                  });
                }
                break;

              case 'content_block_delta':
                // 内容增量更新
                if (chunk.delta.type === 'text_delta') {
                  const text = chunk.delta.text;
                  fullText += text;
                  options.onChunk?.({
                    type: 'text',
                    text
                  });
                }
                break;

              case 'content_block_stop':
                // 内容块结束
                break;

              case 'message_stop':
                // 消息结束
                options.onChunk?.({
                  type: 'done',
                  stopReason: chunk.stop_reason
                });
                break;
            }
          } catch (e) {
            console.error('Parse SSE error:', e);
          }
        }
      }
    }

    return fullText;
  }
}

6.4 SSE (Server-Sent Events) 协议

Claude API 使用 SSE 协议进行流式传输：

事件格式：
data: {"type": "content_block_start", ...}

data: {"type": "content_block_delta", "delta": {"type": "text_delta", "text": "Hello"}}

data: {"type": "content_block_delta", "delta": {"type": "text_delta", "text": " World"}}

data: {"type": "message_delta", "delta": {"stop_reason": "end_turn"}}

data: {"type": "message_stop"}

关键事件类型：

事件类型	说明
message_start	消息开始
content_block_start	内容块开始（文本或工具调用）
content_block_delta	内容增量更新
content_block_stop	内容块结束
message_delta	元数据更新（如 Token 使用）
message_stop	消息结束

6.5 错误处理与重试

class StreamErrorHandler {
  async retryWithBackoff<T>(
    fn: () => Promise<T>,
    maxRetries: number = 3
  ): Promise<T> {
    for (let i = 0; i < maxRetries; i++) {
      try {
        return await fn();
      } catch (error) {
        if (i === maxRetries - 1) throw error;

        // 指数退避
        const delayMs = Math.pow(2, i) * 1000;
        console.log(`请求失败，${delayMs}ms 后重试...`);
        await sleep(delayMs);
      }
    }
    throw new Error('Max retries exceeded');
  }

  handleStreamError(error: any): void {
    if (error.status === 429) {
      console.error('⚠️ API 速率限制，请稍后再试');
    } else if (error.status === 500) {
      console.error('⚠️ API 服务器错误，请稍后再试');
    } else if (error.message.includes('overloaded')) {
      console.error('⚠️ API 负载过高，请稍后再试');
    } else {
      console.error(`❌ 通信错误: ${error.message}`);
    }
  }
}

---

7. UI 层：Ink 驱动的终端渲染

7.1 为什么选择 Ink？

传统 CLI 工具使用 console.log() 线性打印，无法实现：

• ❌ 动态更新（如进度条、Spinner）
• ❌ 彩色输出和格式化
• ❌ 交互式选择（如多选菜单）

重要纠正：Claude Code 并非直接使用 ink npm 包，而是基于 react-reconciler 自建了一套完整的终端渲染引擎（位于 src/ink/ 目录，包含 40+ 个文件）。它借鉴了 Ink 的设计理念，但包含自定义的 Yoga 布局引擎（src/ink/layout/）、ANSI 渲染器、滚动容器、超链接支持等。用 JSX 编写 CLI 界面的概念相同：

// 传统方式
console.log('Loading...');
// 无法更新这行文本

// Ink 方式
<Text color="cyan">
  <Spinner /> Loading...
</Text>
// 可以实时更新 Spinner 动画

7.2 Ink 架构原理

graph LR
    subgraph "React Layer (src/components/)"
        JSX[JSX 组件<br/>Box, Text, ScrollBox]
        VirtualDOM[Virtual DOM]
    end

    subgraph "Custom Ink Engine (src/ink/)"
        Reconciler[react-reconciler<br/>自定义 Reconciler]
        Layout[Yoga Layout Engine<br/>src/ink/layout/]
        Renderer[render-node-to-output.ts<br/>渲染到缓冲区]
    end

    subgraph "Terminal Layer"
        ANSI[ANSI Escape Codes<br/>chalk + 自定义 colorize.ts]
        Stdout[stdout]
    end

    JSX -->|"渲染"| VirtualDOM
    VirtualDOM -->|"Diff 计算"| Reconciler
    Reconciler -->|"布局计算"| Layout
    Layout -->|"生成渲染指令"| Renderer
    Renderer -->|"转换为"| ANSI
    ANSI -->|"render-to-screen.ts"| Stdout

    style Reconciler fill:#61dafb
    style Layout fill:#4caf50

7.3 核心 UI 组件

// [伪代码] Claude Code 的主 UI 组件
// 注意：Box、Text 等组件来自 src/ink/components/，不是 npm 的 ink 包
import { Box, Text } from '../ink/components';
import { Spinner } from '../components/Spinner';
import { useState, useEffect } from 'react';

function ClaudeCodeUI() {
  const [messages, setMessages] = useState<Message[]>([]);
  const [isThinking, setIsThinking] = useState(false);
  const [toolStatus, setToolStatus] = useState<string | null>(null);

  return (
    <Box flexDirection="column">
      {/* 对话历史 */}
      {messages.map((msg, i) => (
        <Message key={i} message={msg} />
      ))}

      {/* 工具执行状态 */}
      {toolStatus && (
        <Box marginTop={1}>
          <Text color="cyan">
            <Spinner type="dots" /> {toolStatus}
          </Text>
        </Box>
      )}

      {/* AI 思考状态 */}
      {isThinking && (
        <Box marginTop={1}>
          <Text color="yellow">
            <Spinner type="simpleDotsScrolling" /> Claude 正在思考...
          </Text>
        </Box>
      )}
    </Box>
  );
}

// 消息组件
function Message({ message }: { message: Message }) {
  if (message.role === 'user') {
    return (
      <Box marginTop={1}>
        <Text bold color="green">You: </Text>
        <Text>{message.content}</Text>
      </Box>
    );
  } else if (message.role === 'assistant') {
    return (
      <Box marginTop={1}>
        <Text bold color="blue">Claude: </Text>
        <MarkdownText>{message.content}</MarkdownText>
      </Box>
    );
  }
  return null;
}

// Markdown 渲染组件
function MarkdownText({ children }: { children: string }) {
  // 简化版：实际会解析 Markdown 并应用样式
  const lines = children.split('\n');
  return (
    <>
      {lines.map((line, i) => {
        // 代码块
        if (line.startsWith('```')) {
          return <Text key={i} color="gray" backgroundColor="black">{line}</Text>;
        }
        // 标题
        if (line.startsWith('#')) {
          return <Text key={i} bold>{line}</Text>;
        }
        // 普通文本
        return <Text key={i}>{line}</Text>;
      })}
    </>
  );
}

7.4 乐观更新（Optimistic UI）

Claude Code 使用乐观更新策略，在工具实际执行前就显示"正在执行"状态：

// [伪代码] 工具调用的乐观更新
function ToolCallHandler() {
  const [toolCalls, setToolCalls] = useState<ToolCall[]>([]);

  // 当 LLM 返回 tool_use 时立即更新 UI
  useEffect(() => {
    claudeAPI.on('tool_use_start', (toolCall) => {
      // 立即显示"正在执行"
      setToolCalls(prev => [...prev, {
        ...toolCall,
        status: 'pending'
      }]);

      // 异步执行工具
      executeToolAsync(toolCall).then(result => {
        // 完成后更新状态
        setToolCalls(prev => prev.map(tc =>
          tc.id === toolCall.id
            ? { ...tc, status: 'completed', result }
            : tc
        ));
      });
    });
  }, []);

  return (
    <Box flexDirection="column">
      {toolCalls.map(tc => (
        <Box key={tc.id} marginTop={1}>
          {tc.status === 'pending' && (
            <Text color="cyan">
              <Spinner /> 执行中: {tc.name}
            </Text>
          )}
          {tc.status === 'completed' && (
            <Text color="green">
              ✓ 完成: {tc.name}
            </Text>
          )}
        </Box>
      ))}
    </Box>
  );
}

7.5 实时性能优化

Ink 使用 React Fiber 架构，可以优先渲染重要的更新：

// 高优先级：用户输入反馈
<Text color="green">{userInput}</Text>

// 中优先级：工具执行状态
<Spinner /> Executing git status...

// 低优先级：日志输出
<Text dimColor>{debugLog}</Text>

7.6 ANSI 颜色与样式

Ink 底层使用 ANSI Escape Codes 实现终端样式：

// ANSI 颜色代码
const ANSI = {
  RESET: '\x1b[0m',
  BOLD: '\x1b[1m',
  RED: '\x1b[31m',
  GREEN: '\x1b[32m',
  YELLOW: '\x1b[33m',
  BLUE: '\x1b[34m',
  CYAN: '\x1b[36m',
};

// 示例输出
console.log(`${ANSI.BOLD}${ANSI.GREEN}✓ Success${ANSI.RESET}`);
// 显示为：粗体绿色的 "✓ Success"

Ink 封装了这些复杂的转义码，提供声明式的 API：

<Text bold color="green">✓ Success</Text>

---

8. 核心模块一：Commands（命令系统）

8.1 什么是 Command？

重要说明：在 v2.1.88 的源码中，commands/ 目录已被标记为 commands_DEPRECATED（见 src/skills/loadSkillsDir.ts），新的推荐方式是使用 skills/ 目录。两者的 Frontmatter 格式相同，但 Skills 提供了更丰富的元数据（whenToUse、model、version 等）。为保持文档的历史连贯性，本章仍以 Command 术语描述。

Command（现称 Skill） 是用户通过 Slash 命令（如 /commit、/review）直接调用的预定义 Prompt。它类似于 ChatGPT 的"自定义指令"，但更强大：

• ✅ 可以预授权工具权限（无需每次确认）
• ✅ 支持参数传递（/feature-dev 实现登录功能）
• ✅ 可以调用其他 Agent
• ✅ 支持 $ARGUMENTS 和索引参数 $0, $1 等变量替换

8.2 Command 文件格式

所有 Command 都是 Markdown + YAML Frontmatter 格式：

---
description: 创建 Git 提交并推送到远程分支
argument-hint: 可选的提交信息
allowed-tools: [Bash(*), Read, TodoWrite]
---

# Commit Push PR 工作流

你是一个 Git 工作流专家。用户想要提交代码并创建 PR。

## 执行步骤

1. 运行 `git status` 查看变更文件
2. 运行 `git diff` 查看具体改动
3. 根据改动生成符合 Conventional Commits 规范的提交信息
4. 执行 `git add .` 和 `git commit -m "..."`
5. 推送到远程：`git push`
6. 使用 `gh pr create` 创建 Pull Request

## 注意事项

- 提交信息必须包含 `Co-Authored-By:` 行（模型名称根据实际使用的模型动态生成，见 `src/utils/commitAttribution.ts`）
- 不要提交 `.env`、`credentials.json` 等敏感文件

8.3 Command 调用流程

sequenceDiagram
    participant User as 用户
    participant Router as Intent Router
    participant Registry as Command Registry
    participant LLM as Claude API
    participant Tools as Tool Engine

    User->>Router: 输入 "/commit 修复登录bug"
    Router->>Registry: 1. 查找 "commit" 命令
    Registry-->>Router: 2. 返回 Command 定义

    Router->>Router: 3. 读取 Markdown 内容
    Router->>Router: 4. 替换 $ARGUMENTS = "修复登录bug"

    Router->>LLM: 5. 注入 System Prompt + Command
    LLM-->>Router: 6. 返回工具调用 (Bash: git status)

    Router->>Tools: 7. 执行 git status
    Tools-->>Router: 8. 返回执行结果

    Router->>LLM: 9. 继续对话循环
    LLM-->>User: 10. 显示最终结果

8.4 核心代码逆向还原

// [伪代码] Command 解析器
class CommandParser {
  // 解析 Markdown 文件
  parse(filePath: string): CommandDefinition {
    const content = fs.readFileSync(filePath, 'utf-8');
    const { attributes, body } = parseFrontmatter(content);

    return {
      name: path.basename(filePath, '.md'),
      description: attributes.description,
      argumentHint: attributes['argument-hint'],
      allowedTools: attributes['allowed-tools'] || [],
      prompt: body, // Markdown 正文作为 Prompt
    };
  }

  // 生成最终 System Prompt
  buildSystemPrompt(command: CommandDefinition, userArgs: string): string {
    // 替换 $ARGUMENTS 变量
    let prompt = command.prompt.replace(/\$ARGUMENTS/g, userArgs);

    // 添加工具权限说明
    if (command.allowedTools.length > 0) {
      prompt += `\n\n## 可用工具\n${command.allowedTools.join(', ')}`;
    }

    return prompt;
  }
}

// 调用示例
const parser = new CommandParser();
const commitCommand = parser.parse('plugins/commit-commands/commands/commit.md');
const systemPrompt = parser.buildSystemPrompt(commitCommand, '修复登录bug');
// 发送到 LLM...

---

9. 核心模块二：Agents（智能代理）

9.1 什么是 Agent？

Agent 是一个自主执行的 AI 实体，拥有独立的：

• 🎯 目标（Goal）
• 🧰 工具集（Tools）
• 🎨 人格（Model + Color）
• 🔒 隔离上下文（不污染主对话）

Agent 与 Command/Skill 的区别：

特性	Command/Skill	Agent
触发方式	用户 /command 调用或 LLM 调用 SkillTool	LLM 调用 AgentTool 派生
执行模式	在主上下文运行	在隔离的子上下文运行
工具权限	需要在 frontmatter 声明	同样需要声明
返回结果	对话式输出	返回结果摘要到主上下文
并行能力	无	支持多 Agent 并行（同一消息多个 AgentTool 调用）
实际工具名	SkillTool	AgentTool (src/tools/AgentTool/)

9.2 Agent 文件格式

---
name: code-explorer
description: 深度分析现有代码库功能，追踪执行路径和架构层次
tools: [Glob, Grep, Read, TodoWrite, WebFetch]
model: sonnet
color: yellow
---

你是一个代码分析专家，专注于追踪和理解功能实现。

## 核心任务

提供完整的功能理解，从入口点到数据存储，贯穿所有抽象层。

## 分析方法

**1. 功能发现**
- 找到入口点（API、UI 组件、CLI 命令）
- 定位核心实现文件
- 绘制功能边界和配置

**2. 代码流程追踪**
- 跟随调用链从输入到输出
- 追踪每一步的数据转换
- 识别所有依赖和集成

**3. 架构分析**
- 绘制抽象层（展示层 → 业务逻辑 → 数据层）
- 识别设计模式和架构决策
- 记录组件间的接口

## 输出要求

提供包含以下内容的全面分析：
- 入口点（文件:行号）
- 逐步执行流程和数据转换
- 关键组件及其职责
- 架构洞察：模式、分层、设计决策
- **必须包含：最关键的 5-10 个文件列表**

9.3 Agent 派生与调度

graph TD
    MainContext[主上下文] -->|"LLM 调用 Agent 工具"| AgentTool[AgentTool<br/>src/tools/AgentTool/]
    AgentTool -->|"createSubagentContext()"| SubContext1[Sub-Agent 1<br/>code-explorer]
    AgentTool -->|"createSubagentContext()"| SubContext2[Sub-Agent 2<br/>code-architect]
    AgentTool -->|"createSubagentContext()"| SubContext3[Sub-Agent 3<br/>code-reviewer]

    SubContext1 -->|"独立执行"| Result1[分析报告 1]
    SubContext2 -->|"独立执行"| Result2[设计方案 2]
    SubContext3 -->|"独立执行"| Result3[审查报告 3]

    Result1 --> Merge[合并结果]
    Result2 --> Merge
    Result3 --> Merge

    Merge -->|"返回主上下文"| MainContext

    style TaskTool fill:#4ecdc4
    style Merge fill:#ffd93d

9.4 核心代码：Agent 调度器

// [伪代码] Agent 调度器
class AgentScheduler {
  // 派生子 Agent
  async spawnAgent(
    agentName: string,
    task: string,
    options: {
      fork?: boolean,    // 是否隔离上下文
      model?: 'sonnet' | 'opus' | 'haiku',
      maxTurns?: number, // 最大对话轮数
    }
  ): Promise<AgentResult> {
    // 1. 从注册表加载 Agent 定义
    const agentDef = this.registry.getAgent(agentName);
    if (!agentDef) throw new Error(`Agent not found: ${agentName}`);

    // 2. 构建子上下文
    const subContext = options.fork
      ? this.createIsolatedContext()  // 隔离上下文（不继承主对话）
      : this.cloneContext();          // 克隆上下文（继承历史）

    // 3. 注入 Agent 的 System Prompt
    subContext.addSystemMessage(agentDef.prompt);
    subContext.addUserMessage(task);

    // 4. 设置工具权限
    subContext.setAllowedTools(agentDef.tools);

    // 5. 执行 Agent Loop（类似主循环）
    let turns = 0;
    while (turns < (options.maxTurns || 20)) {
      // 注意：实际源码中 temperature 固定为 1（API 要求开启思考时必须为 1）
      const response = await this.llm.chat(subContext, {
        model: options.model || agentDef.model || 'sonnet',
        temperature: 1,
      });

      // 如果完成任务，返回结果
      if (response.stopReason === 'end_turn') {
        return {
          agentName,
          transcript: subContext.messages,
          summary: response.content,
        };
      }

      // 执行工具调用
      if (response.toolCalls) {
        const results = await this.toolEngine.execute(response.toolCalls);
        subContext.addToolResults(results);
      }

      turns++;
    }

    // 超时返回
    return { agentName, error: 'Max turns exceeded' };
  }

  // 并行执行多个 Agent
  async spawnParallel(tasks: Array<{agent: string, task: string}>): Promise<AgentResult[]> {
    return Promise.all(
      tasks.map(t => this.spawnAgent(t.agent, t.task, { fork: true }))
    );
  }
}

9.5 实际应用：Feature-Dev 的 7 阶段工作流

feature-dev 插件通过多 Agent 协作实现复杂的功能开发流程：

flowchart TD
    Start[用户: /feature-dev 实现登录功能] --> Phase1[Phase 1: Discovery<br/>理解需求]
    Phase1 --> Phase2[Phase 2: Codebase Exploration<br/>派生 3 个 code-explorer Agents]
    Phase2 --> ReadFiles[读取 Agents 推荐的关键文件]
    ReadFiles --> Phase3[Phase 3: Clarifying Questions<br/>询问未明确的细节]
    Phase3 --> Phase4[Phase 4: Architecture Design<br/>派生 3 个 code-architect Agents]
    Phase4 --> UserApproval{用户批准方案?}
    UserApproval -->|否| Phase4
    UserApproval -->|是| Phase5[Phase 5: Implementation<br/>编写代码]
    Phase5 --> Phase6[Phase 6: Quality Review<br/>派生 3 个 code-reviewer Agents]
    Phase6 --> FixIssues{需要修复?}
    FixIssues -->|是| Phase5
    FixIssues -->|否| Phase7[Phase 7: Summary<br/>总结完成]

    style Phase2 fill:#ffcccb
    style Phase4 fill:#add8e6
    style Phase6 fill:#90ee90

---

10. 核心模块三：Skills（技能系统）

10.1 什么是 Skill？

Skill 是一种可被 LLM 自主调用的 SOP（标准操作流程）。Skill 的元数据（name、description）始终在 System Prompt 中，LLM 根据用户意图判断是否通过 SkillTool 调用某个 Skill。

重要纠正：原文描述 Skill 是"通过触发短语自动激活"的隐式注入。实际源码中，Skill 的触发方式有两种：

1. LLM 主动调用：Skill 元数据列在 System Prompt 中，LLM 判断相关时调用 SkillTool（src/tools/SkillTool/）
2. 用户显式调用：用户输入 /skill-name 直接调用

并不存在基于关键词的自动匹配引擎。

类比：

• 旧版 Command = 用户 /commit 显式调用
• Skill = LLM 看到元数据后自主决策是否调用（半隐式）；也可由用户 /skill-name 显式调用

10.2 Skill 文件格式

---
name: Frontend Design
description: 当用户提到 "design", "UI", "frontend", "用户界面" 时触发。提供高质量前端实现指导。
version: 0.1.0
---

# 前端设计技能

## 触发场景

当检测到以下关键词时自动激活：
- "设计登录页面"
- "优化 UI 性能"
- "实现响应式布局"

## 设计原则

### 1. 组件化思维
- 单一职责原则
- Props 接口清晰
- 避免 Prop Drilling

### 2. 性能优化
- 使用 React.memo 避免不必要渲染
- 代码分割（React.lazy + Suspense）
- 图片懒加载

### 3. 可访问性（a11y）
- 语义化 HTML
- ARIA 标签
- 键盘导航支持

## 代码规范

```tsx
// ✅ 好的实践
function LoginButton({ onClick, disabled, children }: ButtonProps) {
  return (
    <button
      onClick={onClick}
      disabled={disabled}
      aria-label="登录"
      className="btn btn-primary"
    >
      {children}
    </button>
  );
}

// ❌ 避免的做法
function Button(props) {  // 缺少类型定义
  return <div onClick={props.click}>click me</div>;  // 非语义化标签
}

审查清单

• 组件是否可复用？
• 是否有 TypeScript 类型定义？
• 是否处理了加载和错误状态？
• 是否支持深色模式？
• 是否通过了 a11y 测试？

### 10.3 Skill 渐进式加载

Skill 采用**三层加载策略**，平衡 Token 消耗与知识可用性：

```mermaid
graph BT
    subgraph Level3["Level 3: References (磁盘)"]
        Refs["详细文档<br/>代码示例<br/>API 参考"]
        note3["超高 Token 成本<br/>仅在需要时 Read"]
    end

    subgraph Level2["Level 2: SOP Body (上下文)"]
        Body["设计原则<br/>代码规范<br/>审查清单"]
        note2["中等 Token 成本<br/>触发时注入"]
    end

    subgraph Level1["Level 1: Metadata (内存)"]
        Meta["Name<br/>Description<br/>触发短语"]
        note1["极低 Token 成本<br/>常驻内存"]
    end

    Meta -->|"关键词命中"| Body
    Body -->|"需要细节"| Refs

    style Meta fill:#90ee90
    style Body fill:#add8e6
    style Refs fill:#ffcccb

10.4 Skill 注入逻辑

// 实际源码逻辑（src/skills/loadSkillsDir.ts + src/tools/SkillTool/）

// 1. 启动时：加载所有 Skill 的 frontmatter 元数据
async function loadSkillsFromDir(dir: string): Promise<Command[]> {
  const skillDirs = await readdir(dir);
  const skills: Command[] = [];

  for (const skillName of skillDirs) {
    const skillPath = join(dir, skillName, 'SKILL.md');
    if (!await pathExists(skillPath)) continue;

    const content = await readFile(skillPath, 'utf-8');
    const { attributes, body } = parseFrontmatter(content);

    skills.push({
      type: 'prompt',
      name: attributes.name || skillName,
      description: coerceDescriptionToString(attributes.description),
      // 完整内容懒加载 — 调用时才读取 body
      getContent: () => body,
      allowedTools: parseSlashCommandToolsFromFrontmatter(attributes),
      model: parseUserSpecifiedModel(attributes.model),
    });
  }
  return skills;
}

// 2. System Prompt 中列出所有 Skill 元数据，供 LLM 决策
// （在 src/constants/prompts.ts 的 getSystemPrompt 中）

// 3. LLM 决定调用时 → SkillTool.call() 读取完整内容
// ⚠️ 注意：没有关键词匹配引擎，是 LLM 自主决策

// 实际的 Skill 调用流程：
// 用户: "帮我设计一个登录页面"
// LLM 看到 System Prompt 中有: "- Frontend Design: 提供高质量前端实现指导"
// LLM 决定调用: SkillTool({ skill: "Frontend Design", args: "登录页面" })
// SkillTool.call() → 读取 SKILL.md 完整内容 → 替换 $ARGUMENTS
//                   → 返回 Skill SOP 作为用户消息注入后续对话
// LLM 后续回答遵循 Skill 中的设计原则

10.5 Skill vs Command vs Agent：三大能力对比

核心区别：这三者代表了 Claude Code 中不同的知识传递模式。

graph TB
    subgraph User["👤 用户意图层"]
        Intent["用户输入：设计一个登录页面"]
    end

    subgraph Detection["🔍 意图识别层"]
        Router["Intent Router<br/>路由引擎"]
    end

    subgraph Capabilities["🧩 能力执行层"]
        direction LR

        subgraph CommandFlow["⚡ Command 流程<br/><small>显式调用</small>"]
            C1["用户输入：<br/>/feature-dev 登录功能"]
            C2["🎯 精确匹配命令"]
            C3["📋 执行固定流程<br/>7阶段 SOP"]
            C4["✅ 完成任务"]

            C1 --> C2 --> C3 --> C4
        end

        subgraph SkillFlow["📚 Skill 流程<br/><small>隐式注入</small>"]
            S1["用户输入：<br/>设计登录页面"]
            S2["🔎 关键词匹配<br/>design/UI/frontend"]
            S3["💉 注入 Skill SOP<br/>前端设计最佳实践"]
            S4["🧠 AI自主执行<br/>遵循设计原则"]

            S1 --> S2 --> S3 --> S4
        end

        subgraph AgentFlow["🤖 Agent 流程<br/><small>自主决策</small>"]
            A1["Command调用：<br/>/feature-dev"]
            A2["🚀 启动 Agent<br/>code-explorer"]
            A3["🔄 自主规划<br/>搜索→分析→总结"]
            A4["📊 返回报告"]

            A1 --> A2 --> A3 --> A4
        end
    end

    Intent --> Router
    Router -.检测Command.-> CommandFlow
    Router -.检测关键词.-> SkillFlow
    Router -.调用Agent.-> AgentFlow

对比表格

维度	🎯 Skill (用户调用型)	📚 Skill (LLM 调用型)	🤖 Agent
触发方式	/skill-name 用户显式调用	LLM 通过 SkillTool 自主调用	LLM 通过 AgentTool 调用
执行主体	主线程 Core Engine	主线程 Core Engine	独立子上下文 AI 实例
Token 成本	中等（SOP注入）	低（元数据常驻 + 按需加载正文）	高（独立上下文）
适用场景	固定流程任务	通用质量保证、知识注入	复杂自主任务
用户感知	✅ 明确知道调用	⚠️ 半感知（会显示 Skill 工具调用）	✅ 明确知道调用
工具权限	allowed-tools 预定义	allowed-tools 预定义（可选）	tools 预定义
典型例子	/commit 提交代码	前端设计最佳实践	code-explorer 分析

纠正：原文将 Command 和 Skill 描述为完全不同的概念。实际源码中，Command 已被 Skill 统一（commands_DEPRECATED）。Skill 本质上就是更强大的 Command，支持用户显式调用和 LLM 隐式调用两种模式。

10.6 Skill 完整生命周期

sequenceDiagram
    autonumber
    participant User as 👤 用户
    participant Engine as ⚙️ Core Engine
    participant Router as 🔍 Skill Router
    participant Index as 📇 Skill Index<br/>(内存)
    participant FS as 💾 File System
    participant LLM as 🧠 Claude API

    Note over Engine,Index: ═══ Phase 1: 启动时索引构建 ═══

    Engine->>+Router: 初始化 Skill 系统
    Router->>+FS: 扫描 plugins/*/skills/*/SKILL.md
    FS-->>-Router: 返回所有 Skill 文件路径

    loop 每个 Skill 文件
        Router->>+FS: 读取 SKILL.md 的 frontmatter
        FS-->>-Router: 返回 { name, description }
        Router->>Router: 从 description 提取触发短语
        Router->>Index: 存储到内存索引
    end

    Router-->>-Engine: Skill 索引构建完成

    Note over User,LLM: ═══ Phase 2: 运行时触发与注入 ═══

    User->>+Engine: 输入：帮我设计一个登录界面

    Engine->>+Router: 检测触发的 Skills
    Router->>Index: 遍历所有 Skill metadata
    Index-->>Router: 匹配到: frontend-design<br/>(关键词: 设计, 界面)

    Router->>+FS: 读取 frontend-design/SKILL.md 完整内容
    FS-->>-Router: 返回 SOP 内容

    Router->>Engine: 返回触发的 Skill 列表
    Engine->>Engine: 将 Skill SOP 注入 System Prompt

    Note over Engine: System Prompt 组成:<br/>① Core System Prompt<br/>② 用户偏好 (L3)<br/>③ 项目规范 (L2)<br/>④ Skill SOP (frontend-design)

    Engine->>+LLM: 发送请求 (携带注入后的上下文)
    LLM-->>-Engine: AI响应（遵循 Skill 中的设计原则）
    Engine-->>-User: 输出高质量前端代码

    Note over User,LLM: ═══ Phase 3: Skill 持续生效 ═══

    User->>+Engine: 后续消息: 加一个密码强度提示
    Note over Engine: Skill SOP 仍在上下文中<br/>无需重新注入
    Engine->>+LLM: 发送请求
    LLM-->>-Engine: 继续遵循前端设计原则
    Engine-->>-User: 输出符合 a11y 标准的实现

10.7 Skill 设计哲学：渐进式披露

Claude Code 的 Skill 系统采用**渐进式披露（Progressive Disclosure）**设计模式，这是一个经典的 UX 设计原则，应用在了 AI 系统中。

🎯 核心理念

按需加载，恰到好处

不要一次性把所有知识塞给 AI，而是：

1. Level 1（元数据）：启动时加载，极低成本，用于快速匹配
2. Level 2（SOP 主体）：触发时注入，中等成本，提供核心知识
3. Level 3（详细文档）：需要时 Read，高成本，提供深度参考

📊 Token 成本对比

假设某个 Skill 的完整知识库包含：

• Metadata: 100 tokens（name, description, triggers）
• SOP Body: 2000 tokens（设计原则、代码规范）
• References: 10000 tokens（详细 API 文档、示例代码）

传统方式（全量加载）：

• 启动时加载所有 10 个 Skill = 10 × (100 + 2000 + 10000) = 121,000 tokens
• 每次对话都携带这些 tokens
• 即使用户根本不需要某些 Skill

渐进式方式（Claude Code 实现）：

• 启动时加载元数据 = 10 × 100 = 1,000 tokens
• 触发 1 个 Skill 时注入 SOP = 1 × 2000 = 2,000 tokens
• 需要详细文档时再 Read = 0-10,000 tokens（按需）

节省比例：(121,000 - 3,000) / 121,000 ≈ 97.5% 🎉

10.8 实战案例：Skill 如何改变 AI 行为

场景：用户要求实现一个前端表单

❌ 无 Skill 加持的输出

// 用户输入：帮我实现一个登录表单
function LoginForm() {
  const [username, setUsername] = useState('');
  const [password, setPassword] = useState('');

  const handleSubmit = () => {
    // 直接发送请求，没有验证
    fetch('/api/login', {
      method: 'POST',
      body: JSON.stringify({ username, password })
    });
  };

  return (
    <div>
      <input value={username} onChange={e => setUsername(e.target.value)} />
      <input value={password} onChange={e => setPassword(e.target.value)} />
      <button onClick={handleSubmit}>登录</button>
    </div>
  );
}

问题：

• ❌ 没有类型定义
• ❌ input 缺少 label（不符合 a11y）
• ❌ 密码框没有设置 type="password"
• ❌ 没有错误处理
• ❌ 没有加载状态
• ❌ 非语义化标签（应该用 form）

---

✅ 有 Skill 加持的输出（自动触发 frontend-design Skill）

// 用户输入：帮我实现一个登录表单
// [Skill Injected: frontend-design]

interface LoginFormProps {
  onSuccess?: () => void;
  onError?: (error: Error) => void;
}

interface FormData {
  username: string;
  password: string;
}

interface FormErrors {
  username?: string;
  password?: string;
}

function LoginForm({ onSuccess, onError }: LoginFormProps) {
  const [formData, setFormData] = useState<FormData>({
    username: '',
    password: ''
  });
  const [errors, setErrors] = useState<FormErrors>({});
  const [isLoading, setIsLoading] = useState(false);

  const validateForm = (): boolean => {
    const newErrors: FormErrors = {};

    if (!formData.username.trim()) {
      newErrors.username = '请输入用户名';
    }

    if (formData.password.length < 6) {
      newErrors.password = '密码至少6位';
    }

    setErrors(newErrors);
    return Object.keys(newErrors).length === 0;
  };

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();

    if (!validateForm()) return;

    setIsLoading(true);

    try {
      const response = await fetch('/api/login', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(formData)
      });

      if (!response.ok) throw new Error('登录失败');

      onSuccess?.();
    } catch (error) {
      const err = error as Error;
      onError?.(err);
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <form onSubmit={handleSubmit} aria-label="登录表单">
      <div className="form-group">
        <label htmlFor="username">
          用户名
          <span className="required" aria-label="必填">*</span>
        </label>
        <input
          id="username"
          type="text"
          value={formData.username}
          onChange={e => setFormData({ ...formData, username: e.target.value })}
          aria-invalid={!!errors.username}
          aria-describedby={errors.username ? "username-error" : undefined}
          disabled={isLoading}
        />
        {errors.username && (
          <span id="username-error" role="alert" className="error">
            {errors.username}
          </span>
        )}
      </div>

      <div className="form-group">
        <label htmlFor="password">
          密码
          <span className="required" aria-label="必填">*</span>
        </label>
        <input
          id="password"
          type="password"
          value={formData.password}
          onChange={e => setFormData({ ...formData, password: e.target.value })}
          aria-invalid={!!errors.password}
          aria-describedby={errors.password ? "password-error" : undefined}
          disabled={isLoading}
        />
        {errors.password && (
          <span id="password-error" role="alert" className="error">
            {errors.password}
          </span>
        )}
      </div>

      <button
        type="submit"
        disabled={isLoading}
        aria-busy={isLoading}
      >
        {isLoading ? '登录中...' : '登录'}
      </button>
    </form>
  );
}

export default LoginForm;

改进点：

• ✅ 完整的 TypeScript 类型定义
• ✅ 表单验证（前端验证）
• ✅ 错误处理和状态管理
• ✅ 加载状态（防止重复提交）
• ✅ 完整的 ARIA 标签（a11y）
• ✅ 语义化 HTML（form, label）
• ✅ Props 接口设计（回调函数）
• ✅ 错误提示与用户体验

可视化对比

graph LR
    subgraph Without["❌ 无 Skill"]
        W1["用户输入"] --> W2["AI 基础知识"]
        W2 --> W3["低质量输出<br/>缺少最佳实践"]

        style W3 fill:#dc2626,stroke:#fca5a5,color:#fff
    end

    subgraph With["✅ 有 Skill"]
        S1["用户输入"] --> S2["AI 基础知识"]
        S2 --> S3["+ Skill SOP"]
        S3 --> S4["高质量输出<br/>遵循最佳实践"]

        style S3 fill:#7c3aed,stroke:#c4b5fd,color:#fff
        style S4 fill:#16a34a,stroke:#86efac,color:#fff
    end

10.9 Skill 的核心价值

Skill 系统解决了 AI 辅助编程中的一个根本性问题：

如何让 AI 在不明确指示的情况下，自动遵循项目最佳实践？

传统方案：

• ❌ 每次都在 prompt 中重复："请使用 TypeScript，注意 a11y，处理错误..."
• ❌ 依赖 AI 的"通用知识"，质量不稳定
• ❌ 无法针对特定项目定制规范

Skill 方案：

• ✅ 一次定义，自动应用
• ✅ 团队统一标准，质量可预测
• ✅ 针对项目特点定制 SOP
• ✅ 新成员无需培训，AI 自动遵循

类比：Skill 就像团队里的高级工程师在旁边 Code Review，在你写代码时自动提醒最佳实践，而不需要你每次都问。

---

11. 核心模块四：Hooks（钩子与治理）

11.1 什么是 Hook？

Hook 是一个拦截器系统，在关键时刻介入 AI 的执行流程：

• 🛡️ 安全防护：阻止危险命令（如 rm -rf /）
• 📊 审计日志：记录所有工具调用
• 🎯 行为定制：根据项目规则修改 AI 行为
• ⚠️ 警告提示：在敏感操作前提醒用户

11.2 Hook 类型与事件

graph LR
    subgraph "Hook 事件类型（v2.1.88 完整列表）"
        E1[PreToolUse<br/>工具执行前]
        E2[PostToolUse<br/>工具执行后]
        E2b[PostToolUseFailure<br/>工具执行失败后]
        E3[UserPromptSubmit<br/>用户输入提交前]
        E4[Stop<br/>对话结束前]
        E4b[StopFailure<br/>结束检查失败]
        E5[SessionStart<br/>会话开始]
        E6[SessionEnd<br/>会话结束]
        E7a[SubagentStart<br/>子 Agent 启动]
        E7b[SubagentStop<br/>子 Agent 结束]
        E8[PreCompact<br/>上下文压缩前]
        E8b[PostCompact<br/>上下文压缩后]
        E9[Notification<br/>通知事件]
        E10[PermissionRequest<br/>权限请求]
        E11[PermissionDenied<br/>权限拒绝]
    end

    E1 -.->|"可以阻止"| Decision1{允许执行?}
    E2 -.->|"可以修改"| Decision2{修改结果?}
    E3 -.->|"可以修改"| Decision3{修改输入?}
    E4 -.->|"可以阻止"| Decision4{允许退出?}

    style E1 fill:#ff6b6b
    style E2 fill:#4ecdc4
    style E3 fill:#ffe66d
    style E4 fill:#a8dadc

源码出处：完整的 Hook 事件列表定义在 src/entrypoints/sdk/coreTypes.ts 的 HOOK_EVENTS 常量中。

11.3 Hook 配置格式

实际支持四种 Hook 类型（command、prompt、agent、http），以及 if 条件匹配：

{
  "description": "Security Guidance Hook - 拦截危险操作",
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/security_reminder_hook.py",
            "timeout": 10
          }
        ],
        "matcher": "Edit|Write|MultiEdit"
      },
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "检查这个 Bash 命令是否安全：$ARGUMENTS",
            "if": "Bash(rm *)"
          }
        ],
        "matcher": "Bash"
      },
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "验证此代码变更不会引入安全漏洞",
            "timeout": 30
          }
        ],
        "matcher": "Edit|Write"
      },
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://security-api.example.com/check",
            "timeout": 15
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/posttooluse.py",
            "timeout": 10
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/stop.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

四种 Hook 类型说明（源码：src/utils/hooks/hooksSettings.ts）：

• command：启动子进程执行脚本，通过 stdin 传入 JSON，退出码 0=放行、2=阻止
• prompt：将 prompt 文本直接注入当前对话作为系统消息
• agent：启动子 Agent（使用 Haiku 模型），通过 SyntheticOutputTool 返回 {ok, reason} 结构化结果
• http：发送 HTTP 请求到指定 URL，请求体为工具调用信息的 JSON

### 11.4 实战案例：Security Guidance Hook

这是一个真实的安全拦截器，检测 XSS、命令注入等漏洞：

```python
#!/usr/bin/env python3
"""
Security Reminder Hook for Claude Code
检查文件编辑中的安全模式并发出警告
"""

import json
import sys
from datetime import datetime

# 安全模式配置
SECURITY_PATTERNS = [
    {
        "ruleName": "github_actions_workflow",
        "path_check": lambda path: ".github/workflows/" in path
                                  and (path.endswith(".yml") or path.endswith(".yaml")),
        "reminder": """⚠️ 你正在编辑 GitHub Actions 工作流。注意以下安全风险：

1. **命令注入**：不要直接使用 ${{ github.event.issue.title }}
2. **使用环境变量**：通过 env: 传递用户输入
3. **参考指南**：https://github.blog/security/...

❌ 不安全模式：
run: echo "${{ github.event.issue.title }}"

✅ 安全模式：
env:
  TITLE: ${{ github.event.issue.title }}
run: echo "$TITLE"
"""
    },
    {
        "ruleName": "eval_injection",
        "substrings": ["eval("],
        "reminder": "⚠️ eval() 会执行任意代码，存在重大安全风险。考虑使用 JSON.parse() 或其他安全方案。"
    },
    {
        "ruleName": "react_dangerously_set_html",
        "substrings": ["dangerouslySetInnerHTML"],
        "reminder": "⚠️ dangerouslySetInnerHTML 可能导致 XSS 漏洞。确保内容经过 DOMPurify 等库的清理。"
    },
    {
        "ruleName": "innerHTML_xss",
        "substrings": [".innerHTML =", ".innerHTML="],
        "reminder": "⚠️ 直接设置 innerHTML 可能导致 XSS。对于纯文本使用 textContent，HTML 使用 DOMPurify。"
    }
]

def check_patterns(file_path: str, content: str):
    """检查文件路径或内容是否匹配安全模式"""
    normalized_path = file_path.lstrip("/")

    for pattern in SECURITY_PATTERNS:
        # 检查路径模式
        if "path_check" in pattern and pattern["path_check"](normalized_path):
            return pattern["ruleName"], pattern["reminder"]

        # 检查内容模式
        if "substrings" in pattern and content:
            for substring in pattern["substrings"]:
                if substring in content:
                    return pattern["ruleName"], pattern["reminder"]

    return None, None

def main():
    # 读取 Hook 输入（JSON 格式）
    try:
        input_data = json.loads(sys.stdin.read())
    except json.JSONDecodeError:
        sys.exit(0)  # 解析失败，放行

    tool_name = input_data.get("tool_name", "")
    tool_input = input_data.get("tool_input", {})

    # 只检查文件编辑工具
    if tool_name not in ["Edit", "Write", "MultiEdit"]:
        sys.exit(0)

    # 提取文件路径和内容
    file_path = tool_input.get("file_path", "")
    content = tool_input.get("content") or tool_input.get("new_string", "")

    # 检查安全模式
    rule_name, reminder = check_patterns(file_path, content)

    if rule_name and reminder:
        # 输出警告到 stderr
        print(reminder, file=sys.stderr)
        # 退出码 2 = 阻止执行
        sys.exit(2)

    # 放行
    sys.exit(0)

if __name__ == "__main__":
    main()

11.5 Hookify：用户自定义规则引擎

hookify 插件提供了一个可视化的规则编辑器，让用户无需写代码就能定义拦截规则：

# .hookify.rules.md (用户配置文件)

## 规则 1：禁止删除 node_modules
- **名称**：prevent-delete-node-modules
- **启用**：是
- **事件**：bash
- **条件**：
  - 字段：command
  - 操作符：regex_match
  - 模式：`rm.*node_modules`
- **动作**：block
- **消息**：🚫 不要删除 node_modules！请使用 npm clean-install 重新安装。

## 规则 2：Git 提交前提醒
- **名称**：commit-reminder
- **启用**：是
- **事件**：bash
- **条件**：
  - 字段：command
  - 操作符：contains
  - 模式：`git commit`
- **动作**：warn
- **消息**：⚠️ 提交前确认：是否已运行测试？是否更新了文档？

Hookify 架构：

graph LR
    Config[.hookify.rules.md<br/>Markdown 配置] -->|"解析"| Loader[Config Loader<br/>YAML to Python]
    Loader --> Rules[Rule Objects<br/>数据结构]

    Input[Hook 输入<br/>JSON] --> Engine[Rule Engine<br/>规则引擎]
    Rules --> Engine

    Engine --> Matcher{匹配规则?}
    Matcher -->|"否"| Allow[允许执行]
    Matcher -->|"是"| Action{动作类型?}

    Action -->|"block"| Block[阻止 + 显示消息]
    Action -->|"warn"| Warn[警告 + 继续执行]

    style Config fill:#ffe66d
    style Engine fill:#4ecdc4
    style Block fill:#ff6b6b
    style Warn fill:#ffa500

---

12. MCP 协议：连接外部世界

12.1 什么是 MCP？

MCP (Model Context Protocol) 是 Anthropic 推出的标准化的 AI-服务连接协议。它类似于：

• 🔌 USB 协议：统一的接口标准
• 🌐 GraphQL：声明式的能力描述
• 🐳 Docker：封装复杂服务为简单工具

通过 MCP，Claude Code 可以连接：

• 🗄️ 数据库（PostgreSQL, MongoDB）
• 📁 文件系统（本地、S3、Google Drive）
• 🐙 GitHub API（Issues, PRs, Code Search）
• 📊 Asana, Notion（项目管理）
• 🔍 搜索引擎（Google, Brave Search）

12.2 MCP 服务器类型

graph TD
    subgraph "MCP Server Types"
        T1[stdio<br/>本地进程]
        T2[SSE<br/>服务器推送]
        T3[HTTP<br/>REST API]
        T4[WebSocket<br/>双向实时]
    end

    subgraph "Use Cases"
        U1[本地工具<br/>文件系统, Git]
        U2[云服务<br/>GitHub, Asana]
        U3[API 后端<br/>自定义服务]
        U4[实时数据<br/>股票行情]
    end

    T1 --> U1
    T2 --> U2
    T3 --> U3
    T4 --> U4

12.3 MCP 配置示例

方式 1：独立 .mcp.json 文件

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"],
    "env": {
      "LOG_LEVEL": "info"
    }
  },
  "github": {
    "type": "sse",
    "url": "https://mcp.github.com/sse"
  },
  "database": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
    "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
    "env": {
      "DB_URL": "${DATABASE_URL}"
    }
  }
}

方式 2：内嵌在 plugin.json

{
  "name": "my-plugin",
  "version": "1.0.0",
  "mcpServers": {
    "api-service": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

12.4 MCP 工具命名规范

MCP 提供的工具会自动加上前缀：

mcp__plugin_<插件名>_<服务器名>__<工具名>

示例：
- mcp__plugin_asana_asana__asana_create_task
- mcp__plugin_github_github__github_search_issues
- mcp__plugin_db_database__execute_query

在 Command 中使用：

---
description: 创建 Asana 任务
allowed-tools: [
  "mcp__plugin_asana_asana__asana_create_task",
  "mcp__plugin_asana_asana__asana_search_tasks"
]
---

# 任务管理

使用 Asana API 创建和管理任务。

步骤：
1. 询问用户任务标题和描述
2. 调用 mcp__plugin_asana_asana__asana_create_task
3. 确认创建成功

12.5 MCP 生命周期

sequenceDiagram
    participant Plugin as 插件加载器
    participant MCP as MCP Client
    participant Server as MCP Server
    participant LLM as Claude

    Plugin->>MCP: 1. 读取 .mcp.json 配置
    MCP->>Server: 2. 启动 stdio 进程 / 建立 SSE 连接
    Server-->>MCP: 3. 返回工具清单 (tools/list)
    MCP->>MCP: 4. 注册工具到能力表

    LLM->>MCP: 5. 调用 mcp__plugin_x_y__tool
    MCP->>Server: 6. 发送 JSON-RPC 请求
    Server-->>MCP: 7. 返回执行结果
    MCP-->>LLM: 8. 格式化结果

    Note over MCP,Server: 连接保持活跃，支持多次调用

    Plugin->>MCP: 9. 会话结束
    MCP->>Server: 10. 关闭连接 / 终止进程

---

13. 工具系统：执行引擎

13.1 内置工具清单

Claude Code 提供了 30+ 内置工具（源码 src/tools/ 目录下每个子目录对应一个工具），覆盖常见开发场景：

类别	工具名称	源码位置	功能描述
文件操作	Read	FileReadTool/	读取文件内容（支持行号范围、PDF、图片）
	Write	FileWriteTool/	创建或覆盖文件
	Edit	FileEditTool/	精确字符串替换编辑
	NotebookEdit	NotebookEditTool/	编辑 Jupyter Notebook
	Glob	GlobTool/	文件模式匹配查找
	Grep	GrepTool/	正则搜索文件内容（基于 ripgrep）
Shell 操作	Bash	BashTool/	执行 Shell 命令（支持后台、超时、沙箱）
	PowerShell	PowerShellTool/	Windows PowerShell 执行
代理管理	Agent	AgentTool/	派生子 Agent（隔离上下文）
	SendMessage	SendMessageTool/	向已有 Agent 发送消息
	TaskCreate	TaskCreateTool/	创建后台任务
	TaskGet	TaskGetTool/	获取任务状态
	TaskList	TaskListTool/	列出所有任务
	TaskOutput	TaskOutputTool/	获取任务输出
	TaskStop	TaskStopTool/	停止任务
	TaskUpdate	TaskUpdateTool/	更新任务
	TodoWrite	TodoWriteTool/	管理待办事项列表
模式切换	EnterPlanMode	EnterPlanModeTool/	进入计划模式（只读）
	ExitPlanMode	ExitPlanModeTool/	退出计划模式
	EnterWorktree	EnterWorktreeTool/	进入 Git Worktree 隔离环境
	ExitWorktree	ExitWorktreeTool/	退出 Worktree
用户交互	AskUserQuestion	AskUserQuestionTool/	询问用户选择
	Skill	SkillTool/	调用 Skill
	ToolSearch	ToolSearchTool/	搜索延迟加载的工具定义
网络请求	WebFetch	WebFetchTool/	获取网页内容
	WebSearch	WebSearchTool/	执行网络搜索
定时调度	RemoteTrigger	RemoteTriggerTool/	远程触发代理
	ScheduleCron	ScheduleCronTool/	创建定时任务
MCP 工具	mcp__*	MCPTool/	MCP 服务器提供的动态工具
实验性	Sleep	SleepTool/	等待指定时间
	REPL	REPLTool/	交互式代码执行

纠正：原文列出 "MultiEdit"、"KillShell"、"Task" 等工具名，这些在实际源码中不存在。正确名称分别是 Edit（支持 replace_all）、TaskStop、Agent。

13.2 工具执行流程

sequenceDiagram
    participant LLM as Claude API
    participant Router as Tool Router
    participant Hooks as Hook System
    participant Executor as Tool Executor
    participant OS as Operating System

    LLM->>Router: 1. 返回 tool_calls: [Bash, Read, Grep]
    Router->>Router: 2. partitionToolCalls() 分区

    Note over Router: 智能并行策略：<br/>连续只读工具 → 并行批次<br/>写入工具 → 串行批次

    loop 遍历每个批次
        alt 只读批次（Read, Grep 等）
            par 并行执行
                Router->>Hooks: 3a. PreToolUse Hook
                Hooks-->>Router: 放行
                Router->>Executor: 4a. Read 执行
                Router->>Executor: 4b. Grep 执行
            end
        else 写入批次（Bash, Edit 等）
            Router->>Hooks: 3b. PreToolUse Hook
            alt Hook 阻止
                Hooks-->>LLM: 拦截并返回错误消息
            else Hook 放行
                Router->>Executor: 4c. 串行执行

                alt 内置工具
                    Executor->>OS: 5a. 调用系统 API
                    OS-->>Executor: 返回结果
                else MCP 工具
                    Executor->>MCP: 5b. JSON-RPC 调用 MCP Server
                    MCP-->>Executor: 返回结果
                end
            end
        end

        Executor->>Hooks: 6. PostToolUse Hook（可修改结果）
        Executor-->>Router: 7. 返回工具结果
    end

    Router-->>LLM: 8. 汇总所有结果，继续对话循环

13.3 工具权限控制

每个 Command 和 Agent 都必须声明允许使用的工具：

---
# 明确列出工具
allowed-tools: [Read, Glob, Grep, TodoWrite]

# 使用通配符 — 允许所有参数的 Bash 调用
allowed-tools: [Bash(*), Edit, Write]

# 使用参数匹配 — 仅允许 git 开头的 Bash 命令
allowed-tools: ["Bash(git *)"]

# 允许特定 MCP 工具
allowed-tools: [
  "mcp__plugin_github_github__github_search_code",
  "mcp__plugin_github_github__github_create_issue"
]
---

补充：allowed-tools 中的通配符语法 Bash(git *) 由 src/tools/BashTool/bashPermissions.ts 中的 matchWildcardPattern 函数实现，支持 glob 风格匹配。

权限检查逻辑：

// [伪代码] 工具权限检查器
class ToolPermissionChecker {
  // 检查工具调用是否被允许
  isAllowed(toolName: string, allowedTools: string[]): boolean {
    // 1. 精确匹配
    if (allowedTools.includes(toolName)) {
      return true;
    }

    // 2. 通配符匹配（如 "Bash(*)" 允许所有 Bash 调用）
    for (const pattern of allowedTools) {
      if (pattern.endsWith('(*)')) {
        const baseTool = pattern.replace('(*)', '');
        if (toolName === baseTool) {
          return true;
        }
      }

      // 3. MCP 工具通配符（如 "mcp__plugin_x_y__*"）
      if (pattern.endsWith('*')) {
        const prefix = pattern.slice(0, -1);
        if (toolName.startsWith(prefix)) {
          return true;
        }
      }
    }

    return false;
  }

  // 拦截未授权的工具调用
  async checkAndExecute(toolCall: ToolCall, context: Context): Promise<ToolResult> {
    const allowedTools = context.getAllowedTools();

    if (!this.isAllowed(toolCall.name, allowedTools)) {
      return {
        error: `工具 ${toolCall.name} 未被授权。允许的工具：${allowedTools.join(', ')}`
      };
    }

    // 执行工具
    return await this.toolExecutor.execute(toolCall);
  }
}

---

14. 实战案例：Feature-Dev 插件剖析

14.1 插件文件结构

plugins/feature-dev/
├── .claude-plugin/
│   └── plugin.json           # 插件元数据
├── commands/
│   └── feature-dev.md        # /feature-dev 命令
├── agents/
│   ├── code-explorer.md      # 代码探索 Agent
│   ├── code-architect.md     # 架构设计 Agent
│   └── code-reviewer.md      # 代码审查 Agent
└── README.md                 # 使用文档

14.2 命令定义（feature-dev.md 节选）

---
description: 引导式功能开发，包含代码库理解和架构聚焦
argument-hint: 可选的功能描述
---

# Feature Development

你正在帮助开发者实现新功能。遵循系统化方法：深入理解代码库，识别并询问所有未明确的细节，设计优雅的架构，然后实现。

## 核心原则

- **提出澄清性问题**：识别所有歧义、边界情况和未明确的行为。提出具体、实际的问题而非假设。在实现前等待用户回答。在理解代码库后、设计架构前尽早提问。
- **先理解再行动**：首先阅读和理解现有代码模式
- **阅读 Agent 识别的文件**：启动 Agent 时，要求它们返回最重要文件的列表。Agent 完成后，阅读这些文件以建立详细上下文再继续。
- **简单优雅**：优先考虑可读性、可维护性、架构合理性
- **使用 TodoWrite**：全程跟踪所有进度

---

## Phase 1: Discovery

**目标**：理解需要构建什么

初始请求：$ARGUMENTS

**行动**：
1. 创建包含所有阶段的待办列表
2. 如果功能不清楚，询问用户：
   - 他们要解决什么问题？
   - 功能应该做什么？
   - 有哪些约束或需求？
3. 总结理解并与用户确认

---

## Phase 2: Codebase Exploration

**目标**：在高层和低层理解相关的现有代码和模式

**行动**：
1. 并行启动 2-3 个 code-explorer Agent。每个 Agent 应该：
   - 全面追踪代码，专注于全面理解抽象、架构和控制流
   - 针对代码库的不同方面（如类似功能、高层理解、架构理解、用户体验等）
   - 包含 5-10 个关键文件的列表

   **Agent Prompt 示例**：
   - "找到类似 [功能] 的特性并全面追踪其实现"
   - "绘制 [功能区域] 的架构和抽象，全面追踪代码"
   - "分析 [现有功能/区域] 的当前实现，全面追踪代码"
   - "识别与 [功能] 相关的 UI 模式、测试方法或扩展点"

2. Agent 返回后，请阅读 Agent 识别的所有文件以建立深入理解
3. 展示全面的发现总结和发现的模式

---

## Phase 3: Clarifying Questions

**目标**：在设计前填补空白并解决所有歧义

**关键**：这是最重要的阶段之一。不要跳过。

**行动**：
1. 审查代码库发现和原始功能请求
2. 识别未明确的方面：边界情况、错误处理、集成点、范围边界、设计偏好、向后兼容性、性能需求
3. **以清晰、有组织的列表向用户展示所有问题**
4. **在进入架构设计前等待答案**

如果用户说"你认为最好的方式"，提供你的建议并获得明确确认。

---

## Phase 4: Architecture Design

**目标**：设计具有不同权衡的多种实现方法

**行动**：
1. 并行启动 2-3 个 code-architect Agent，具有不同的关注点：最小变更（最小改动，最大复用）、清晰架构（可维护性，优雅抽象）或务实平衡（速度 + 质量）
2. 审查所有方法并形成你对哪个最适合此特定任务的看法（考虑：小修复 vs 大功能，紧急性，复杂性，团队背景）
3. 向用户展示：每种方法的简要总结、权衡比较、**你的建议及理由**、具体实现差异
4. **询问用户更喜欢哪种方法**

---

## Phase 5: Implementation

**目标**：构建功能

**未获用户批准不要开始**

**行动**：
1. 等待明确的用户批准
2. 阅读前面阶段识别的所有相关文件
3. 按照选定的架构实现
4. 严格遵循代码库约定
5. 编写清晰、文档良好的代码
6. 在进展时更新待办事项

---

## Phase 6: Quality Review

**目标**：确保代码简单、DRY、优雅、易读且功能正确

**行动**：
1. 并行启动 3 个 code-reviewer Agent，具有不同关注点：简单性/DRY/优雅、错误/功能正确性、项目约定/抽象
2. 整合发现并识别你建议修复的最高严重性问题
3. **向用户展示发现并询问他们想做什么**（现在修复、稍后修复或按原样继续）
4. 根据用户决定解决问题

---

## Phase 7: Summary

**目标**：记录完成的工作

**行动**：
1. 标记所有待办事项完成
2. 总结：
   - 构建了什么
   - 做出的关键决策
   - 修改的文件
   - 建议的后续步骤

14.3 Agent 定义示例（code-explorer.md）

---
name: code-explorer
description: 通过追踪执行路径、绘制架构层、理解模式和抽象、记录依赖关系来深度分析现有代码库功能
tools: [Glob, Grep, Read, TodoWrite, WebFetch]
model: sonnet
color: yellow
---

你是一个代码分析专家，专注于追踪和理解功能实现。

## 核心任务

从入口点到数据存储，贯穿所有抽象层，提供功能的完整理解。

## 分析方法

**1. 功能发现**
- 找到入口点（API、UI 组件、CLI 命令）
- 定位核心实现文件
- 绘制功能边界和配置

**2. 代码流程追踪**
- 跟随从输入到输出的调用链
- 追踪每一步的数据转换
- 识别所有依赖和集成
- 记录状态变化和副作用

**3. 架构分析**
- 绘制抽象层（展示 → 业务逻辑 → 数据）
- 识别设计模式和架构决策
- 记录组件间的接口
- 注意横切关注点（认证、日志、缓存）

**4. 实现细节**
- 关键算法和数据结构
- 错误处理和边界情况
- 性能考虑
- 技术债务或改进领域

## 输出指导

提供全面的分析，帮助开发者深入理解功能，足以修改或扩展它。包括：

- 带文件:行号引用的入口点
- 带数据转换的逐步执行流程
- 关键组件及其职责
- 架构洞察：模式、分层、设计决策
- 依赖关系（外部和内部）
- 关于优势、问题或机会的观察
- **你认为绝对必要的文件列表，以理解所讨论的主题**

以最大的清晰度和实用性组织你的响应。始终包含具体的文件路径和行号。

14.4 工作流演示

sequenceDiagram
    participant User as 用户
    participant Main as Main Context
    participant Explorer as Code Explorer Agent
    participant Architect as Code Architect Agent
    participant Reviewer as Code Reviewer Agent

    User->>Main: /feature-dev 实现用户登录
    Main->>Main: Phase 1: 理解需求
    Main->>User: 确认功能范围

    User->>Main: 确认：支持邮箱/密码登录
    Main->>Main: Phase 2: 探索代码库

    par 并行探索
        Main->>Explorer: "找到类似的认证实现"
        Main->>Explorer: "分析当前的用户系统"
        Main->>Explorer: "识别 API 路由模式"
    end

    Explorer-->>Main: 返回关键文件列表
    Main->>Main: 读取推荐文件

    Main->>User: Phase 3: 询问澄清问题<br/>- 密码加密方式？<br/>- Token 存储位置？<br/>- 支持第三方登录吗？
    User->>Main: 回答问题

    Main->>Main: Phase 4: 设计架构

    par 并行设计
        Main->>Architect: "最小变更方案"
        Main->>Architect: "清晰架构方案"
        Main->>Architect: "务实平衡方案"
    end

    Architect-->>Main: 返回 3 种设计方案
    Main->>User: 展示方案 + 推荐

    User->>Main: 批准"务实平衡方案"
    Main->>Main: Phase 5: 实现功能<br/>(编写代码)

    Main->>Main: Phase 6: 质量审查

    par 并行审查
        Main->>Reviewer: "检查简单性/DRY"
        Main->>Reviewer: "检查功能正确性"
        Main->>Reviewer: "检查项目约定"
    end

    Reviewer-->>Main: 返回审查报告
    Main->>User: 展示问题列表

    User->>Main: 修复高优先级问题
    Main->>Main: Phase 7: 总结完成
    Main-->>User: ✅ 功能完成

---

15. CLI 使用方式与最佳实践

15.1 核心命令清单

命令	功能	使用场景
claude	启动交互式会话	日常开发对话
claude "快速任务"	单次执行	CI/CD 脚本、自动化
claude --debug	调试模式	排查插件问题、查看 MCP 连接
/help	查看帮助	了解可用命令
/init	初始化项目	首次使用，生成 CLAUDE.md
/commit	智能提交	自动生成提交信息
/review	代码审查	提交前质量检查
/compact	压缩上下文	感觉 AI 反应慢时
/clear	清空会话	切换任务时
/cost	查看成本	监控 Token 消耗
/mcp	查看 MCP 服务器	调试外部服务连接

15.2 项目配置：CLAUDE.md

这是 Claude Code 的"项目宪法"，定义 AI 的行为准则：

# 项目规范：MyApp

## 代码风格

- **语言**：TypeScript（严格模式）
- **格式化**：Prettier + ESLint
- **命名**：
  - 组件：PascalCase (`UserProfile.tsx`)
  - 函数：camelCase (`getUserById`)
  - 常量：UPPER_SNAKE_CASE (`MAX_RETRY_COUNT`)

## 架构原则

- **组件化**：每个组件单一职责
- **类型安全**：所有函数必须有类型定义
- **错误处理**：使用 Result 类型而非异常
- **测试**：核心逻辑覆盖率 > 80%

## 禁止操作

- ❌ 不要使用 `any` 类型
- ❌ 不要直接修改 `package.json`（使用 npm install）
- ❌ 不要提交 `.env` 文件

## Git 规范

遵循 Conventional Commits：

feat: 新功能 fix: Bug 修复 docs: 文档更新 refactor: 重构 test: 测试 chore: 构建/工具变更

## 测试命令

```bash
npm test              # 运行所有测试
npm run test:watch    # 监视模式
npm run test:e2e      # E2E 测试

部署流程

1. 运行 npm run build
2. 确保所有测试通过
3. 创建 PR 到 main 分支
4. 等待 CI 通过
5. 合并后自动部署到 staging

### 15.3 最佳实践

#### 1. 使用 TodoWrite 跟踪任务

```markdown
# 用户
实现用户注册功能

# Claude
我会使用 TodoWrite 来跟踪这个任务：

1. [pending] 设计数据库 schema
2. [pending] 实现 API 端点
3. [pending] 编写单元测试
4. [pending] 添加前端表单
5. [pending] 集成验证码

现在开始第一步...

2. 善用 Plan Mode（Shift+Tab）

Plan Mode 会禁用所有写操作，只允许读取和分析。适合：

• 🔍 探索不熟悉的代码库
• 📋 制定实现计划
• 🤔 架构设计讨论

3. 自定义 Hookify 规则

# .hookify.rules.md

## 规则：生产环境保护
- **启用**：是
- **事件**：bash
- **条件**：
  - 字段：command
  - 操作符：regex_match
  - 模式：`kubectl.*delete|helm.*uninstall`
- **动作**：block
- **消息**：🚫 生产环境操作已被阻止！请联系 DevOps 团队。

## 规则：大文件警告
- **启用**：是
- **事件**：file
- **条件**：
  - 字段：file_path
  - 操作符：regex_match
  - 模式：`\.png$|\.jpg$|\.mp4$`
- **动作**：warn
- **消息**：⚠️ 你正在提交二进制文件。考虑使用 Git LFS 或 CDN。

---

16. 总结：Markdown 驱动的 AI 应用新范式

16.1 核心设计哲学

Claude Code 的插件生态系统证明了一个重要理念：

用 Markdown 定义能力，用 LLM 执行逻辑，用 Hook 保障安全。

这种范式的优势：

传统代码	Claude Code 插件
用 Python/JS 编写逻辑	用 Markdown 描述意图
硬编码的 if-else	LLM 动态推理
需要编译/部署	热加载（无需重启）
学习曲线陡峭	接近自然语言
难以维护	易于修改和理解

16.2 技术架构精髓

mindmap
  root((Claude Code<br/>插件生态))
    分层设计
      微内核
      插件扩展
      能力注册
    声明式能力
      Commands
      Agents
      Skills
    治理机制
      Hooks
      权限控制
      安全拦截
    外部连接
      MCP 协议
      stdio/SSE/HTTP
      多服务集成
    开发者体验
      Markdown 驱动
      热加载
      调试友好

16.3 适用场景与限制

适用场景：

• ✅ 自动化开发工作流（commit, review, PR）
• ✅ 代码库探索和文档生成
• ✅ 定制化开发助手（企业内部规范）
• ✅ 连接外部服务（数据库、API、CI/CD）

当前限制：

• ⚠️ 核心引擎闭源（无法深度定制）
• ⚠️ 依赖网络（需要 Claude API）
• ⚠️ Token 成本（大型项目可能昂贵）
• ⚠️ Hook 调试较困难（需要 --debug 模式）

16.4 未来展望

基于当前架构，我们可以预见：

1. 更多官方插件：数据库管理、DevOps、测试生成
2. 插件市场：类似 VS Code Extensions
3. 本地模型支持：降低成本，提高隐私
4. 可视化编辑器：拖拽式创建 Command/Agent
5. 企业版：SSO、审计日志、合规性控制

---

附录：快速参考

A. 文件格式速查

Command 格式：

---
description: 描述
argument-hint: 参数提示
allowed-tools: [工具列表]
---

# Prompt 内容
$ARGUMENTS 会被替换为用户输入

Agent 格式：

---
name: agent-name
description: 描述
tools: [工具列表]
model: sonnet|opus|haiku
color: yellow|blue|green
---

# Agent 指令
详细的执行逻辑...

Skill 格式（新版统一格式，替代旧版 Command）：

---
name: Skill Name
description: 功能描述（LLM 根据此判断何时调用）
version: 1.0.0
model: sonnet                         # 可选：指定模型
allowed-tools: [Read, Glob, Grep]     # 可选：预授权工具
argument-hint: 可选的参数提示           # 可选
---

# SOP 内容
标准操作流程...

$ARGUMENTS 会被替换为用户输入
也支持索引参数：$0, $1, $ARGUMENTS[0]

Hook 格式：

{
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 script.py",
            "timeout": 10
          }
        ],
        "matcher": "Edit|Write"
      }
    ]
  }
}

B. 环境变量

• ${CLAUDE_PLUGIN_ROOT} - 插件根目录（必须使用）
• ${API_KEY} - 自定义 API 密钥
• ${DATABASE_URL} - 数据库连接字符串
• ENABLE_SECURITY_REMINDER - 启用/禁用安全提示（0/1）

C. 调试技巧

# 启用调试日志
claude --debug

# 查看 MCP 服务器状态
/mcp

# 查看插件列表
/help

# 强制压缩上下文
/compact

# 查看 Token 使用
/cost

# 清空会话重新开始
/clear

D. Bun 适配层（源码运行必备）

Claude Code 核心引擎使用 Bun 编译，依赖 bun:bundle 和 bun:ffi 两个 Bun-only 模块。通过 extracted/ 中的 shim 层可在 Node.js 下运行：

extracted/
├── loader.mjs           # ESM Loader Hook — 拦截 bun:bundle/bun:ffi 导入
├── shims/
│   ├── register.ts      # 入口：注册 MACRO 全局常量
│   ├── macro.ts         # MACRO.VERSION 等构建时常量
│   ├── bun-bundle.ts    # feature() 函数 shim — 所有特性开关默认 false
│   └── bun-ffi.ts       # FFI 桩 — dlopen/ptr 空实现
└── stubs/               # Anthropic 内部包的空壳 (@ant/*, @anthropic-ai/mcpb)

feature() 函数是核心适配点 — Bun 编译期将 feature('FLAG') 替换为字面量实现 Dead Code Elimination（DCE），Node 运行时通过 shim 返回 false：

// shims/bun-bundle.ts
const FEATURE_FLAGS: Record<string, boolean> = {};
export function feature(flag: string): boolean {
  return FEATURE_FLAGS[flag] ?? false;  // 默认全部关闭
}

E. 源码校正勘误表

原文内容	纠正	依据源码位置
"Sonnet 4.5/Opus 4.5"	当前版本为 Sonnet 4.6/Opus 4.6	src/constants/prompts.ts:118-123
"CapabilityRegistry 类"	不存在该类，组件分散合并	src/hooks/useMergedTools.ts
"Intent Router"	不存在该模块	直接由 processUserInput() 处理
"Skill 通过关键词自动激活"	LLM 通过 SkillTool 自主调用	src/tools/SkillTool/
"commands/ 目录"	已标记为 commands_DEPRECATED	src/skills/loadSkillsDir.ts:68
"MultiEdit 工具"	不存在，Edit 支持 replace_all	src/tools/FileEditTool/
"KillShell 工具"	不存在，使用 TaskStop	src/tools/TaskStopTool/
"Task 工具"	实际名为 Agent (AgentTool)	src/tools/AgentTool/
"使用 ink npm 包"	自建 Ink 引擎 (40+ 文件)	src/ink/
"temperature: 0.7"	固定为 1（思考模式要求）	src/services/api/claude.ts:1693
"config.json 存偏好"	全局偏好在 ~/.claude/CLAUDE.md	src/memdir/memdir.ts
Hook 事件仅 9 种	实际 15 种（含 PermissionDenied 等）	src/entrypoints/sdk/coreTypes.ts
Hook 仅 command 类型	支持 command/prompt/agent/http 四种	src/utils/hooks/hooksSettings.ts

---

17. 三足鼎立：Claude Code vs Codex vs Gemini CLI

基于 Claude Code v2.1.88、OpenAI Codex（开源版）、Gemini CLI v0.21.0 的源码对比分析。

17.1 基础画像

维度	Claude Code	OpenAI Codex	Gemini CLI
开发商	Anthropic	OpenAI	Google
核心语言	TypeScript (Bun 编译)	Rust + TypeScript	TypeScript
运行时	Bun（发布）/ Node（兼容）	Rust 原生二进制	Node.js 20+
UI 框架	自建 Ink 引擎 (react-reconciler)	Rust TUI (ratatui)	Ink (npm 包)
代码规模	~800 文件，闭源核心 + 开源插件	45+ Rust 模块，完全开源	~200 文件，完全开源
后端模型	Claude Sonnet/Opus 4.6	GPT-4 系列	Gemini 2.5 Pro/Flash
许可证	核心闭源，插件 MIT	Apache 2.0	Apache 2.0

17.2 架构哲学对比

三者看似功能相同，但架构哲学截然不同：

Claude Code：  Markdown 驱动 + 微内核插件
               "用文档定义能力，让 LLM 执行逻辑"

Codex：        Rust 系统级 + 沙箱隔离优先
               "安全第一，性能极致，系统级隔离"

Gemini CLI：   TypeScript 全栈 + 最简设计
               "清晰分层，标准 React 模式，易于理解"

Claude Code — 微内核 + 插件生态

┌──────────────────────────────────────────┐
│         Markdown 插件生态层               │
│  Skills(*.md) │ Agents(*.md) │ Hooks     │
├──────────────────────────────────────────┤
│         微内核引擎（闭源 Bun 编译）         │
│  query() 主循环 │ 30+ 内置工具 │ MCP      │
├──────────────────────────────────────────┤
│         自建 Ink 渲染引擎                  │
│  react-reconciler + Yoga Layout          │
└──────────────────────────────────────────┘
核心理念：业务逻辑全部外化到 Markdown 文件

Codex — Rust 系统级安全优先

┌──────────────────────────────────────────┐
│         TypeScript SDK 层                │
│  开发者 API │ 嵌入式集成                    │
├──────────────────────────────────────────┤
│         Rust 核心引擎                     │
│  SQ/EQ 异步队列 │ 工具注册表 │ MCP         │
├──────────────────────────────────────────┤
│         多平台沙箱隔离层                    │
│  macOS Seatbelt │ Linux Landlock+Seccomp │
│  Windows RestrictedToken                 │
└──────────────────────────────────────────┘
核心理念：系统级沙箱隔离，Rust 内存安全保障

Gemini CLI — TypeScript 全栈最简

┌──────────────────────────────────────────┐
│         CLI UI 层 (Ink + React 19)       │
│  Composer │ MessageDisplay │ Themes      │
├──────────────────────────────────────────┤
│         Core 业务逻辑层                   │
│  GeminiClient │ ToolScheduler │ Hooks    │
├──────────────────────────────────────────┤
│         Gemini API + MCP                 │
│  REST + SSE │ Stdio/HTTP 传输            │
└──────────────────────────────────────────┘
核心理念：清晰的两包分层（cli + core），标准 React 模式

17.3 核心机制深度对比

工具系统

特性	Claude Code	Codex	Gemini CLI
工具数量	30+ 内置	8 内置	10 内置
工具定义	Zod Schema + prompt() 函数	Rust trait ToolHandler	类继承 BaseDeclarativeTool
并行执行	只读工具并行，写入串行	顺序执行	顺序执行
权限控制	Hook + canUseTool 多层	Starlark 策略引擎	shouldConfirmExecute()
沙箱	可选沙箱（特定命令）	系统级强制沙箱	无沙箱
独有工具	Agent（子代理）、Skill、PlanMode、Worktree	apply_patch（diff 补丁）	memory（AI 自动写入记忆）

// Claude Code — buildTool 工厂 + isReadOnly 影响并行策略
export const BashTool = buildTool({
  name: 'Bash',
  inputSchema: z.object({ command: z.string(), timeout: z.number().optional() }),
  isReadOnly(input) { return isReadOnlyCommand(input.command); },
  async call(input, ctx) { return await exec(input.command); },
});

// Codex — Rust trait 实现，编译期类型安全
pub trait ToolHandler: Send + Sync {
    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, ToolError>;
}

// Gemini CLI — 类继承 + 声明式 schema
class ReadFileTool extends BaseDeclarativeTool {
  readonly kind = 'Read';
  readonly requiresConfirmation = false;
  async execute(signal: AbortSignal): Promise<ToolResult> { ... }
}

记忆系统

特性	Claude Code	Codex	Gemini CLI
全局记忆	~/.claude/CLAUDE.md	~/.codex/instructions.md	~/.gemini/GEMINI.md
项目记忆	./CLAUDE.md（多级向上查找）	./AGENTS.md	./GEMINI.md（多级 + @import）
AI 自动记忆	无（只读）	无	有（MemoryTool 自动写入）
注入方式	Attachment 消息	System Prompt	System Prompt
会话持久化	session storage	~/.codex/sessions/	支持 --resume

关键差异：Gemini CLI 是唯一支持 AI 自动写入记忆 的工具 — LLM 可以调用 MemoryTool 将事实保存到 GEMINI.md 的 ## Gemini Added Memories 部分。Claude Code 和 Codex 的记忆文件都是用户手动维护的。

上下文压缩

特性	Claude Code	Codex	Gemini CLI
触发阈值	90% 上下文窗口	接近上下文限制	50% 上下文窗口
保留策略	保留最近 N 轮	保留头尾，删除中间	保留最近 30%
快照格式	Summary + Snapshot	摘要 + 环境差异	XML 结构化（含文件操作记录）
手动触发	/compact 命令	无	无

Gemini CLI 压缩最激进 — 50% 就触发，但快照最结构化：
<state_snapshot>
  <user_goal>实现用户认证</user_goal>
  <file_operations>READ: login.ts, MODIFIED: jwt.ts</file_operations>
  <progress>1. [DONE] JWT 生成  2. [IN PROGRESS] 修复测试</progress>
</state_snapshot>

Claude Code 最保守 — 90% 才触发，但支持手动 /compact。
Codex 独有环境差异策略 — 只发送 <environment_context_diff>。

Hook / 安全系统

特性	Claude Code	Codex	Gemini CLI
Hook 事件	15 种	无 Hook 系统	11 种
Hook 类型	command / prompt / agent / http	—	command（shell 脚本）
安全核心	Hook → 权限 → 可选沙箱	策略引擎 + 强制沙箱	工具确认 + Hook
策略语言	JSON	Starlark (.codexpolicy)	JSON
AI 验证	agent 类型 Hook	无	无
独有事件	PermissionDenied, SubagentStart	—	BeforeModel, AfterModel

Claude Code 的 Hook 最丰富（15 种事件 + 4 种执行方式）；Codex 没有 Hook 但有最强系统级沙箱；Gemini CLI 独有 AI 模型调用生命周期钩子（BeforeModel/AfterModel）。

插件/扩展系统

特性	Claude Code	Codex	Gemini CLI
插件系统	完整插件生态（Marketplace）	无	无
扩展方式	Skills/Agents/Hooks + MCP	MCP + AGENTS.md	MCP + GEMINI.md + Hooks
技能注入	Skill 渐进式加载	无	无
子代理	AgentTool（隔离上下文，可并行）	无	无

这是 Claude Code 最大的差异化优势 — 唯一拥有完整插件生态的工具。

17.4 通信与异步模型

特性	Claude Code	Codex	Gemini CLI
API 通信	Anthropic SDK（流式）	OpenAI Responses API（流式）	Google GenAI SDK (REST+SSE)
异步模型	AsyncGenerator (query 主循环)	SQ/EQ 队列 (Rust channels)	AsyncGenerator (Turn)
后台任务	TaskCreate/TaskStop	无	无
并发工具	最多 10 个只读工具并行	顺序	顺序

17.5 性能与安全权衡

安全性    Codex ████████████ > Claude Code ████████ > Gemini CLI █████
          系统级沙箱             多层 Hook            工具确认

扩展性    Claude Code ████████████ > Gemini CLI ████████ > Codex █████
          插件+Skill+Agent+Hook   MCP+Hook+记忆        MCP only

性能      Codex ████████████ > Claude Code ████████ > Gemini CLI ██████
          Rust 原生               Bun 编译             Node.js

易读性    Gemini CLI ████████████ > Claude Code ████████ > Codex ██████
          纯 TS，清晰分层          TS 但闭源编译         Rust 高门槛

开放性    Codex ████████████ = Gemini CLI ████████████ > Claude Code ████
          Apache 2.0 全开源       Apache 2.0 全开源     核心闭源

17.6 谁适合谁？

场景	推荐	原因
企业级团队协作	Claude Code	插件生态 + Skill SOP 统一团队标准
安全敏感环境	Codex	系统级沙箱 + Starlark 策略引擎
快速上手/学习	Gemini CLI	代码最清晰，纯 TS，Google 免费额度
CI/CD 自动化	Codex	Rust 性能 + codex exec 非交互模式
自定义 AI 行为	Claude Code	Markdown 驱动的 Skill + Agent 扩展
源码学习/二开	Gemini CLI / Codex	完全开源，社区活跃

17.7 本质差异总结

三个工具解决同一个问题 — 让 LLM 在终端里执行编程任务 — 但各自的"灵魂"完全不同：

graph LR
    subgraph Claude["Claude Code 的灵魂"]
        CC1["Markdown 驱动的知识注入"]
        CC2["用文档定义能力"]
        CC3["插件生态 + 子 Agent 并行"]
        CC1 --> CC2 --> CC3
        style CC1 fill:#7c3aed,stroke:#c4b5fd,color:#fff
        style CC2 fill:#7c3aed,stroke:#c4b5fd,color:#fff
        style CC3 fill:#7c3aed,stroke:#c4b5fd,color:#fff
    end

    subgraph Codex["Codex 的灵魂"]
        CX1["系统级安全隔离"]
        CX2["Rust 性能 + 沙箱"]
        CX3["Starlark 策略引擎"]
        CX1 --> CX2 --> CX3
        style CX1 fill:#059669,stroke:#6ee7b7,color:#fff
        style CX2 fill:#059669,stroke:#6ee7b7,color:#fff
        style CX3 fill:#059669,stroke:#6ee7b7,color:#fff
    end

    subgraph Gemini["Gemini CLI 的灵魂"]
        GM1["最小可行 AI Agent"]
        GM2["清晰分层 + 纯 TS"]
        GM3["AI 自动记忆 + 结构化压缩"]
        GM1 --> GM2 --> GM3
        style GM1 fill:#dc2626,stroke:#fca5a5,color:#fff
        style GM2 fill:#dc2626,stroke:#fca5a5,color:#fff
        style GM3 fill:#dc2626,stroke:#fca5a5,color:#fff
    end

• Claude Code 本质上是一个知识管理系统 — Skills 渐进式加载用最少 Token 给 AI 最多知识，子 Agent 并行让多个 AI 实例分工协作
• Codex 本质上是一个安全执行环境 — 跨平台沙箱（Seatbelt/Landlock/Seccomp）确保 AI 操作不会伤害系统
• Gemini CLI 本质上是一个极简 Agent 框架 — 200 文件覆盖全功能，AI 能主动学习用户偏好，适合学习和快速定制

---

参考资料：

• Claude Code 官方文档
• OpenAI Codex 源码
• Gemini CLI 源码
• Model Context Protocol 规范
• Claude API 文档
• extracted/src/ — 逆向提取的 v2.1.88 核心源码

致谢：本文基于 claude-code 官方仓库和逆向提取的核心引擎源码分析。v2.0 版本基于实际源码校正了多处不准确描述，并新增了与 Codex/Gemini CLI 的三方对比。

---

昨天凌晨，群里又传来一张截图：某互联网团队研发收缩 30%，通知里只有一句话——“AI 提效，减少人力”。

十分钟后，群里有人发了三条消息： “兄弟们还好吗？” “现在转测试晚不晚？” “程序员这碗饭是不是要没了？”

这波“程序员失业论”之所以刺痛人，不是因为情绪脆弱，而是因为很多人只看到了 AI 的生成速度，没有看到软件研发真正昂贵的那一面——长期维护与零回归。

如果你把中山大学和阿里联合发布的 SWE-CI 看完，再回头看“失业论”，你会发现：真正要被淘汰的，不是程序员这个职业本身，而是低质量、不可持续的交付方式。

这轮淘汰不是先淘汰程序员，而是先淘汰低质量交付。

01 失业焦虑为什么突然集体爆发：我们被“首轮效率”迷住了

这两年最容易制造焦虑的画面，是那种极其丝滑的演示：一句需求，几十秒出页面；一句报错，几分钟出补丁。

它确实强，强到很多人下意识得出结论：写代码已经工业化，程序员开始被压缩成提示词操作员。

但真实研发不是短视频。 真实研发的主战场是：需求反复变更、接口持续演化、历史系统包袱、跨团队协同、线上回归控制、持续发布压力。

企业真正付钱的，从来不只是“做出来”，而是“半年后还能稳稳地改”。

Before：大家盯着首轮产出速度。 After：企业真正买单的是长期可维护性。

能跑通是起点，跑得久才是门槛。

02 SWE-CI 的价值：它第一次把“会不会越改越坏”摆上台面

SWE-CI 为什么会引爆讨论？因为它换了题。

过去很多评测是“给你一个 Issue，做一次修复”。 SWE-CI 则把 Agent 放进持续集成循环，反复经历“运行测试 -> 定义需求 -> 修改代码”，去观察长期演进能力。

它的几个关键信息非常硬：

• 100 个真实仓库演化任务
• 平均跨 233 天、71 次提交（这是数据历史跨度，不是实验时长）
• 核心观察之一是零回归率：整个维护过程里能不能不把旧功能改坏

这相当于把行业争论从“会不会写”升级到“能不能长期维护”。

AI 最强的地方在生成，最难的地方在守成。

03 站在老板视角：裁的是人头成本，买回来的常常是技术债

“一个人 + AI 顶三个人”在某些场景成立，尤其是短周期、低耦合、一次性交付任务。

问题是，企业不是靠一次性交付活着。 企业靠的是连续上线、稳定质量、可追责、可迭代。

很多团队最近都踩进同一个坑：

• 短期看：人力成本下降，报表漂亮
• 中期看：回归和返工上升，节奏被打乱
• 长期看：核心系统越来越脆，谁都不敢改

这就是“效率幻觉”：把工作量前移，把风险后移。

Before：优化看季度。 After：竞争看三年后的持续迭代能力。

省下的人力成本，可能在未来变成翻倍偿还的维护成本。

04 站在程序员视角：真正危险的不是替代，而是分化

“程序员会不会失业？” 会发生结构性变化，但不会整体蒸发。

先被压缩的，往往是纯搬运型工作：机械 CRUD、模板式拼装、低上下文依赖的重复劳动。

持续升值的，反而是这三类能力：

• 把模糊业务拆成可验证路径的能力
• 在架构、测试、发布之间控制回归风险的能力
• 把 AI 纳入团队生产系统，而不是停留在个人工具层的能力

岗位重心正在迁移： 从“写多少代码”迁移到“对结果负责到什么深度”。

AI 时代的铁饭碗，不是敲键盘速度，而是系统级责任感。

05 站在团队视角：未来护城河是“低回归率组织”

过去团队比拼人均产出。 现在顶级团队比拼的是：在高迭代下，谁还能把回归率压住。

你会发现跑得稳的团队都有共同点： AI 进流程了，但质量治理没有外包给 AI。

他们把评审、测试、灰度、回滚、审计做成机制； 把需求拆解、埋点验证、实验复盘做成习惯。

机制强，AI 是杠杆。 机制弱，AI 是噪音。

Before：单点提效，局部很快。 After：系统提效，整体可持续。

未来不是“人和 AI 比”，而是“有体系的人机协作”对“无体系的单兵作战”。

06 写在最后：别只问“会不会失业”，先问“能不能长期负责”

SWE-CI 最有价值的提醒，不是“AI 还不够强”，而是“评估标准要升级”：

从一次性正确，升级到长期可维护； 从功能上线，升级到持续演进； 从个人效率，升级到组织质量。

所以真正该焦虑的，不是模型变强。 真正该焦虑的是：我们还在用旧能力模型，竞争新岗位。

下一轮分水岭已经出现： 能把 AI 产出转成稳定工程结果的人，会越来越值钱； 只会“先把代码写出来”的人，会越来越被动。

最后留给评论区一个问题： 如果你是技术负责人，今年只能保一件事，你会优先保“上线速度”，还是“零回归率”？

时代不会淘汰程序员，时代只淘汰无法持续交付价值的程序员。

---

参考：

• SWE-CI 论文： arxiv.org/abs/2603.03…
• SWE-CI 项目： github.com/SKYLENAGE-A…
• SWE-CI 数据集： huggingface.co/datasets/sk…

现代Web应用中，当用户在页面间快速切换时，常常会遇到一些正在进行的网络请求继续执行的问题。这不仅会浪费服务器资源，还可能导致页面状态不一致。本文将介绍如何在Vue项目中通过路由守卫实现自动取消pending请求的功能，提高应用的性能和用户体验。

问题背景

在单页应用（SPA）中，用户可能会在短时间内快速切换多个页面。如果前一个页面的网络请求尚未完成，而用户已经跳转到新页面，这些未完成的请求可能会：

1. 继续执行并返回数据，导致新页面的状态被错误覆盖
2. 占用服务器资源处理不必要的请求
3. 可能引发竞态条件，导致数据不一致

解决方案：使用AbortController API

现代浏览器提供了AbortController API，可以用来取消fetch请求和axios请求。Vue项目中可以通过以下方式实现自动取消pending请求：

实现原理

1. 存储pending请求：使用Map数据结构存储所有正在进行的请求及其控制器
2. 路由守卫拦截：在路由切换时检查并取消所有pending请求
3. 请求生命周期管理：在请求开始时添加到pending列表，在请求完成后移除

实现解析

1. 创建请求控制器存储

在src/utils/http.js中，我们使用Map来存储所有pending请求的控制器：

// 存储所有pending请求的控制器
export const pendingRequests = new Map()

2. 请求拦截器中添加控制器

在axios的请求拦截器中，为每个请求创建AbortController并存储：

http.interceptors.request.use(config => {
  const controller = new AbortController()
  const requestKey = Symbol() // 使用Symbol确保唯一性
  config.requestKey = requestKey
  config.signal = controller.signal
  pendingRequests.set(requestKey, controller)
  return config
})

3. 响应拦截器中移除控制器

在响应拦截器中，请求完成后从pending列表中移除对应的控制器：

http.interceptors.response.use(
  response => {
    const requestKey = response.config.requestKey
    pendingRequests.delete(requestKey)
    return response
  }
)

4. 路由守卫中取消pending请求

在src/main.js中，通过路由守卫在页面切换时取消所有pending请求：

import { pendingRequests } from './utils/http'

router.beforeEach((to, from, next) => {
  if (pendingRequests.size > 0) {
    // 遍历并取消所有pending的请求
    pendingRequests.forEach(controller => controller.abort())
    // 清空Map
    pendingRequests.clear()
  }
  next()
})

完整流程图

graph TD
    A[发起请求] --> B[创建AbortController]
    B --> C[存储控制器到pendingRequests]
    C --> D[发送请求]
    D --> E[请求完成]
    E --> F[从pendingRequests移除控制器]

    G[路由切换] --> H[检查pendingRequests]
    H --> I{pendingRequests有请求?}
    I -->|是| J[遍历并取消所有请求]
    J --> K[清空pendingRequests]
    I -->|否| L[继续路由跳转]
    K --> L

优势

1. 资源优化：避免不必要的网络请求，减少服务器负载
2. 用户体验：防止旧页面数据影响新页面状态
3. 状态管理：确保页面状态的一致性
4. 错误处理：通过axios的isCancel方法可以优雅地处理取消的请求

注意事项

1. 白名单处理：可以根据需要为某些重要请求添加白名单，不进行取消
2. 错误处理：正确处理被取消的请求，避免影响用户体验
3. 性能考虑：Map操作的时间复杂度为O(1)，适合频繁的增删操作

总结

通过在路由守卫中自动取消pending请求，我们可以显著提升单页应用的性能和用户体验。这个实现利用了现代浏览器的AbortController API，结合Vue的路由系统和axios的拦截器机制，提供了一个优雅的解决方案。

在实际项目中，这种模式可以有效地管理网络请求的生命周期，确保应用的稳定性和响应性。希望这篇文章能帮助你更好地理解和实现这一重要功能！

背景

上个月我接手了一个老牌的DeFi收益聚合器项目的前端维护工作。这个项目大概两年前开发的，前端核心库用的是 ethers.js v5，配合着一些自定义的 Provider 封装和事件轮询逻辑。刚开始只是修几个小 bug，但当我需要添加对新链（比如 Arbitrum）的支持时，问题就来了。

老代码里到处都是 new ethers.providers.JsonRpcProvider() 的硬编码，钱包连接逻辑和业务逻辑耦合得很深，添加一个新链得改七八个文件。更头疼的是，项目里有些自定义的 BigNumber 处理逻辑在 ethers.js v6 里已经不兼容了，升级版本风险太大。就在我纠结是硬着头皮重构老代码，还是找个新方案时，团队里另一个在做新项目的同事提到了 Viem，说它类型安全、模块化，而且和 Wagmi 搭配起来开发效率很高。我研究了一下，决定拿一个相对独立的功能模块——用户质押和领取奖励的页面——作为“试验田”，尝试用 Viem 彻底替换掉 ethers.js。

问题分析

我选择的功能模块主要做三件事：

1. 读取用户在当前链上的质押余额和待领取奖励。
2. 让用户进行质押（调用合约的 stake 方法）。
3. 让用户领取奖励（调用合约的 claimRewards 方法）。

用 ethers.js 的老代码大概是这样的骨架：

import { ethers } from 'ethers';
import stakingABI from './abis/staking.json';

const provider = new ethers.providers.Web3Provider(window.ethereum);
const signer = provider.getSigner();
const stakingContract = new ethers.Contract(STAKING_ADDRESS, stakingABI, signer);

// 读取数据
const userBalance = await stakingContract.balanceOf(userAddress);
const pendingRewards = await stakingContract.earned(userAddress);

// 发送交易
const stakeTx = await stakingContract.stake(amount);
await stakeTx.wait();

思路很直接，但问题也很明显：Provider 和 Signer 的创建与钱包状态绑定死，ABI 管理松散，错误处理简陋。我的迁移目标很明确：用 Viem 的 PublicClient 和 WalletClient 来分离读和写，用 TypeScript 生成强类型的合约接口，并整合进现有的 React 上下文里。

一开始我以为就是简单的 API 替换，但真正动手才发现，从“面向对象”的 ethers.js 思维切换到“函数式”的 Viem 思维，以及处理两者在数据类型（尤其是 BigNumber 和 bigint）上的差异，才是真正的挑战。

核心实现

第一步：搭建 Viem 客户端与替换读取逻辑

首先，我安装了必要的包：viem 和 @wagmi/core（为了复用项目已有的 Wagmi 配置）。我的策略是，先不碰钱包连接和交易发送，只把数据读取的部分换掉。

在 ethers.js 里，一个 Provider 既负责读也负责写（通过 Signer）。Viem 则明确分成了 PublicClient（读）和 WalletClient（写）。我创建了一个公共的读取客户端：

// src/lib/viemClient.ts
import { createPublicClient, http, PublicClient } from 'viem';
import { mainnet, arbitrum } from 'viem/chains'; // 从老配置里拿到链信息

// 根据当前链ID创建对应的客户端
export function getPublicClient(chainId: number): PublicClient {
  const chain = [mainnet, arbitrum].find(c => c.id === chainId) || mainnet;
  return createPublicClient({
    chain,
    transport: http(), // 这里先用公开RPC，后面可以替换成项目自己的节点
  });
}

接下来是重头戏：合约调用。我不想再手动管理 ABI JSON 文件了。Viem 鼓励使用 @wagmi/cli 或 abitype 来生成类型。我用了更直接的方式，利用 Viem 的 createContractFunctionArgs 思路，手动为我的质押合约定义了一个类型化的“读”对象。这里有个坑：Viem 的合约函数返回的数值类型默认是 bigint，而我的前端界面渲染逻辑到处都在用 ethers.utils.formatUnits 来处理 BigNumber。我必须统一处理这个转换。

// src/contracts/stakingContract.ts
import { getPublicClient } from '@/lib/viemClient';
import stakingABI from './abis/staking.json' assert { type: 'json' }; // 暂时沿用老ABI

export const STAKING_ADDRESS = '0x...'; // 合约地址

// 封装一个类型安全的读取函数
export async function getUserStakingInfo(userAddress: `0x${string}`, chainId: number) {
  const publicClient = getPublicClient(chainId);

  // 注意：这里返回的是 bigint
  const [balance, rewards] = await Promise.all([
    publicClient.readContract({
      address: STAKING_ADDRESS,
      abi: stakingABI,
      functionName: 'balanceOf',
      args: [userAddress],
    }) as Promise<bigint>,
    publicClient.readContract({
      address: STAKING_ADDRESS,
      abi: stakingABI,
      functionName: 'earned',
      args: [userAddress],
    }) as Promise<bigint>,
  ]);

  // 统一转换：bigint -> 格式化的字符串（这里假设代币精度为18）
  const formatBigInt = (value: bigint) => Number(value) / 10**18; // 简单处理，生产环境建议用库
  return {
    balance: formatBigInt(balance),
    pendingRewards: formatBigInt(rewards),
  };
}

在 React 组件里，我就可以把老的 ethers 调用替换成：

// 老代码
// const balance = await stakingContract.balanceOf(address);

// 新代码
const { balance, pendingRewards } = await getUserStakingInfo(address, chainId);

第一步很顺利，界面数据显示正常。这给了我很大信心。

第二步：处理钱包连接与交易发送

这是最核心也最容易出错的部分。在 ethers.js 里，我们从 window.ethereum 创建 Provider，然后 getSigner()。Viem 的 WalletClient 概念类似，但创建方式更多样。我选择与项目已有的 Wagmi 连接器集成，通过 Wagmi 的 useAccount 和 useWalletClient 钩子来获取。

这里有个关键细节：Viem 的 writeContract 方法返回的是交易哈希（0x${string}），而不是一个像 ethers.js 那样的交易对象（包含 wait 方法）。你需要用 PublicClient 的 waitForTransactionReceipt 来等待交易确认。

// src/hooks/useStakingAction.ts
import { useAccount, useWalletClient } from 'wagmi';
import { getPublicClient } from '@/lib/viemClient';
import { STAKING_ADDRESS, stakingABI } from '@/contracts/stakingContract';

export function useStakingAction() {
  const { address, chainId } = useAccount();
  const { data: walletClient } = useWalletClient();

  const stake = async (amount: bigint) => {
    if (!walletClient || !address) throw new Error('钱包未连接');

    try {
      // 1. 发送交易，获取哈希
      const hash = await walletClient.writeContract({
        address: STAKING_ADDRESS,
        abi: stakingABI,
        functionName: 'stake',
        args: [amount],
        account: address,
      });
      console.log('交易哈希:', hash);

      // 2. 等待交易确认
      const publicClient = getPublicClient(chainId!);
      const receipt = await publicClient.waitForTransactionReceipt({ hash });
      console.log('交易确认，区块号:', receipt.blockNumber);
      return receipt;
    } catch (error) {
      console.error('质押失败:', error);
      // 这里可以细化错误处理，比如用户拒绝、gas不足等
      throw error;
    }
  };

  const claimRewards = async () => {
    // 逻辑类似，调用 `claimRewards` 函数
    if (!walletClient || !address) throw new Error('钱包未连接');
    const hash = await walletClient.writeContract({
      address: STAKING_ADDRESS,
      abi: stakingABI,
      functionName: 'claimRewards',
      account: address,
    });
    const publicClient = getPublicClient(chainId!);
    return await publicClient.waitForTransactionReceipt({ hash });
  };

  return { stake, claimRewards };
}

在组件中使用就非常清晰了：

const StakingButton: React.FC = () => {
  const [amount, setAmount] = useState('');
  const { stake } = useStakingAction();
  const handleStake = async () => {
    const amountInWei = BigInt(parseFloat(amount) * 10**18); // 转换精度
    await stake(amountInWei);
    // ... 成功后刷新数据
  };
  return <button onClick={handleStake}>质押</button>;
};

第三步：集成与错误边界处理

替换了核心逻辑后，我需要把新的 Viem 客户端集成到项目的上下文中，并处理好可能出现的错误。我创建了一个 ViemProvider 上下文，用来在不同的组件中共享 PublicClient 和合约方法。

另外，我遇到了一个非常实际的坑：合约事件监听。老代码用 ethers.Contract 的 on 方法监听事件来更新 UI。Viem 提供了 watchContractEvent，但它的用法是函数式的，返回一个取消监听的函数，并且需要自己管理生命周期。

// 在组件或Hook中监听质押事件
useEffect(() => {
  if (!address || !chainId) return;

  const publicClient = getPublicClient(chainId);
  const unwatch = publicClient.watchContractEvent({
    address: STAKING_ADDRESS,
    abi: stakingABI,
    eventName: 'Staked',
    args: { user: address }, // 只监听当前用户的事件
    onLogs: (logs) => {
      console.log('新的质押事件:', logs);
      // 触发UI数据更新
      refetchUserInfo();
    },
    onError: (error) => {
      console.error('监听事件出错:', error);
    }
  });

  // 组件卸载时取消监听
  return () => unwatch();
}, [address, chainId]);

完整代码示例

以下是一个简化但可运行的 React 组件，展示了如何使用我们上面封装的逻辑：

// src/components/StakingPanel.tsx
import React, { useState, useEffect } from 'react';
import { useAccount } from 'wagmi';
import { getUserStakingInfo } from '@/contracts/stakingContract';
import { useStakingAction } from '@/hooks/useStakingAction';

const StakingPanel: React.FC = () => {
  const { address, chainId } = useAccount();
  const { stake, claimRewards } = useStakingAction();
  const [userInfo, setUserInfo] = useState({ balance: 0, pendingRewards: 0 });
  const [stakeAmount, setStakeAmount] = useState('');
  const [isLoading, setIsLoading] = useState(false);

  // 加载用户数据
  const loadUserInfo = async () => {
    if (!address || !chainId) return;
    setIsLoading(true);
    try {
      const info = await getUserStakingInfo(address, chainId);
      setUserInfo(info);
    } catch (error) {
      console.error('加载数据失败:', error);
    } finally {
      setIsLoading(false);
    }
  };

  useEffect(() => {
    loadUserInfo();
  }, [address, chainId]);

  const handleStake = async () => {
    if (!stakeAmount) return;
    setIsLoading(true);
    try {
      const amountInWei = BigInt(Math.floor(parseFloat(stakeAmount) * 10**18));
      await stake(amountInWei);
      setStakeAmount('');
      await loadUserInfo(); // 刷新数据
      alert('质押成功！');
    } catch (error: any) {
      alert(`质押失败: ${error?.shortMessage || error.message}`);
    } finally {
      setIsLoading(false);
    }
  };

  const handleClaim = async () => {
    setIsLoading(true);
    try {
      await claimRewards();
      await loadUserInfo();
      alert('领取成功！');
    } catch (error: any) {
      alert(`领取失败: ${error?.shortMessage || error.message}`);
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <div>
      <h2>我的质押</h2>
      {isLoading && <p>加载中...</p>}
      <p>质押余额: {userInfo.balance}</p>
      <p>待领取奖励: {userInfo.pendingRewards}</p>

      <div>
        <input
          type="number"
          value={stakeAmount}
          onChange={(e) => setStakeAmount(e.target.value)}
          placeholder="输入质押数量"
          disabled={isLoading}
        />
        <button onClick={handleStake} disabled={isLoading}>
          质押
        </button>
      </div>

      <button onClick={handleClaim} disabled={isLoading || userInfo.pendingRewards <= 0}>
        领取奖励
      </button>
    </div>
  );
};

export default StakingPanel;

踩坑记录

1. bigint 序列化错误（JSON.stringify）：这是第一个拦路虎。当我将从 Viem 合约调用中获取的 bigint 类型的状态直接放入 React 状态或传递给 JSON.stringify 时，控制台会报错“Do not know how to serialize a BigInt”。解决方法：在数据层（如 getUserStakingInfo 函数中）就将其转换为 number 或 string。对于大数，可以使用 viem 自带的 formatUnits 函数或转换为字符串 value.toString()。

2. 钱包客户端（WalletClient）获取为 undefined：在 useStakingAction 钩子中，useWalletClient() 返回的 data 可能为 undefined，尤其是在钱包连接初始状态或切换链时。解决方法：增加严格的空值检查，并在 UI 上给出明确的禁用状态或提示。确保 Wagmi 配置正确，连接器支持当前链。

3. 事件监听内存泄漏：最初我在组件中直接调用 watchContractEvent 而没有在 useEffect 中返回清理函数，导致组件卸载后监听依然存在，控制台会有警告，并可能引发状态更新错误。解决方法：严格遵守 useEffect 的生命周期，将 watchContractEvent 返回的 unwatch 函数在清理阶段调用。

4. 交易模拟错误信息不直观：walletClient.writeContract 失败时，抛出的错误对象有时很深，直接 error.message 可能是一串复杂的 RPC 错误。解决方法：利用 Viem 错误工具类，如 parseContractError（在较新版本中）或 decodeErrorResult 来解析。在实践中，我发现 error.shortMessage 或 error.details 通常包含了可读性更强的信息，可以优先展示给用户。

小结

这次迁移就像给老房子换了一套更现代化的水电管道，过程有点折腾，但完成后维护性和扩展性肉眼可见地提升了。Viem 的函数式、类型安全设计，强迫我写出更清晰、解耦的代码。最大的收获不是学会了一个新库的 API，而是理解了如何用“客户端分离”和“类型优先”的思想来构建更健壮的 Web3 前端。下一步，我打算用 @wagmi/cli 来自动生成所有合约的完整类型化接口，彻底告别手写 ABI 导入的日子。