SuperAPI AI 工具集

regenerating a technical summary of stellar-core

编程与开发

查看项目

更新于 10-16 06:39

技能介绍

用途

该技能描述为 stellar-core 生成(或重新生成)整套技术摘要技能文档的流程。这些摘要为 AI 智能体提供关于每个子系统以及整个系统的紧凑架构上下文,目标是让智能体无需阅读全部源代码即可理解架构。

输出产物

该流程生成:

  • 21 个子系统摘要文件,位于 .claude/skills/subsystem-summary-of-$X/SKILL.md
  • 1 个全系统摘要文件,位于 .claude/skills/stellar-core-summary/SKILL.md

子系统列表

src/ 下的以下子系统目录各自单独摘要:

子系统 源目录 说明
bucket src/bucket/ Bucket list 与合并机制
catchup src/catchup/ 账本追赶 / 同步逻辑
crypto src/crypto/ 哈希、签名、密钥管理
database src/database/ SQL 数据库抽象
herder src/herder/ 共识协调、交易队列
history src/history/ 历史归档管理
historywork src/historywork/ 历史操作的工作任务
invariant src/invariant/ 运行时不变式检查
ledger src/ledger/ 账本状态管理、LedgerTxn
main src/main/ 应用、配置、事件循环
overlay src/overlay/ P2P 网络层
process src/process/ 子进程管理
protocol-curr src/protocol-curr/ 当前协议 XDR 定义
rust src/rust/(不含 soroban/) C++/Rust 桥接、非 soroban 的 Rust
soroban-env src/rust/soroban/p26/soroban-env-{common,host}/ 某一协议版本的 soroban 环境
scp src/scp/ SCP 共识协议
simulation src/simulation/ 网络模拟、负载生成
test src/test/ 测试工具与基础设施
transactions src/transactions/ 交易 / 操作处理
util src/util/ 工具类与辅助函数
work src/work/ 异步工作调度框架

流程

阶段 1:生成子系统摘要(可并行)

对上述每个子系统目录,启动一个并行子智能体,指令如下:

  1. 读取该子系统目录下所有 .h、.cpp 和/或 .rs 文件的全部源代码,排除任何测试文件(文件名含 "test" 或 "Test" 的文件,或以 Tests.cpp、Test.cpp、test.cpp 结尾的文件)。
  2. 在 .claude/skills/subsystem-summary-of-$X/SKILL.md 创建技能文档。
  3. 使用以下模板撰写文档:
---
name: "subsystem-summary-of-$X"
description: "read this skill for a token-efficient summary of the $X subsystem"
---

# Subsystem: $X

## Key Classes and Data Structures
...

## Key Modules
...

## Key Functions
...

## Control Loops, Threads, and Tasks
...

## Ownership Relationships
...

## Key Data Flows
...

摘要应约为 10KB,重点包括:

  • 关键类 / 数据结构及简要描述
  • 关键模块及其职责
  • 主要类中的关键函数
  • 关键控制循环、线程和/或任务摘要
  • 数据结构之间的所有权关系
  • 组件之间的关键数据流

特殊情况

  • protocol-curr:聚焦 XDR 类型定义、枚举、联合体及类型关系。
  • rust(非 soroban):包含 C++/Rust 桥接机制(CXX bridge),涉及 src/rust/src/ 和 src/rust/*.h、src/rust/*.cpp 文件,但排除 src/rust/soroban/。
  • soroban-env:从某一协议版本目录(当前为 p26)读取,具体为 soroban-env-common/src/ 和 soroban-env-host/src/。涵盖 Val 类型、Env trait、Host 内部实现、预算 / 计量、存储模型和 VM 调度。
  • test:包含测试工具与基础设施,而非测试本身。读取全部内容,但仍跳过纯单个测试用例文件(*Tests.cpp)。

阶段 2:生成全系统摘要

在所有子系统摘要完成后,启动一个子智能体:

  1. 一起读取全部 21 个子系统摘要文件。
  2. 创建 .claude/skills/stellar-core-summary/SKILL.md。
  3. 撰写约 30KB 的摘要,涵盖:
  • 系统概述(stellar-core 是什么)
  • 架构概述(组件关系)
  • 核心子系统(每个子系统一段简洁描述)
  • 线程模型(跨子系统的所有线程类型)
  • 关键数据流(交易生命周期、账本关闭、追赶、历史发布、overlay 消息传递)
  • 所有权层级(Application → managers)
  • 横切关注点(协议版本管理、不变式、指标、日志、进程管理、工作调度)
  • Soroban 集成(Rust/C++ FFI、Host 运行时)
  • 测试基础设施
  • 关键设计模式(代码库中反复出现的模式)

描述应表明,这是针对 stellar-core 任何广泛范围任务的良好初始上下文。

何时重新生成

在以下情况重新生成摘要:

  • 对某子系统进行重大架构变更
  • 新增子系统
  • 跨多个子系统发生重大重构
  • soroban 协议版本推进(将 p26 引用更新为最新版本)

备注

  • soroban 协议版本目录(当前为 p26)在重新生成时应更新为最新版本。
  • 每个子系统摘要目标约 10KB;全系统摘要目标约 30KB。
  • 所有摘要使用带 name: 和 description: 字段的 YAML frontmatter。
  • 目标是提供足够上下文,让 AI 智能体无需阅读全部源代码即可理解架构。