用途
该技能描述为 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:生成子系统摘要(可并行)
对上述每个子系统目录,启动一个并行子智能体,指令如下:
- 读取该子系统目录下所有
.h、.cpp和/或.rs文件的全部源代码,排除任何测试文件(文件名含 "test" 或 "Test" 的文件,或以 Tests.cpp、Test.cpp、test.cpp 结尾的文件)。 - 在
.claude/skills/subsystem-summary-of-$X/SKILL.md创建技能文档。 - 使用以下模板撰写文档:
---
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:生成全系统摘要
在所有子系统摘要完成后,启动一个子智能体:
- 一起读取全部 21 个子系统摘要文件。
- 创建
.claude/skills/stellar-core-summary/SKILL.md。 - 撰写约 30KB 的摘要,涵盖:
- 系统概述(stellar-core 是什么)
- 架构概述(组件关系)
- 核心子系统(每个子系统一段简洁描述)
- 线程模型(跨子系统的所有线程类型)
- 关键数据流(交易生命周期、账本关闭、追赶、历史发布、overlay 消息传递)
- 所有权层级(Application → managers)
- 横切关注点(协议版本管理、不变式、指标、日志、进程管理、工作调度)
- Soroban 集成(Rust/C++ FFI、Host 运行时)
- 测试基础设施
- 关键设计模式(代码库中反复出现的模式)
描述应表明,这是针对 stellar-core 任何广泛范围任务的良好初始上下文。
何时重新生成
在以下情况重新生成摘要:
- 对某子系统进行重大架构变更
- 新增子系统
- 跨多个子系统发生重大重构
- soroban 协议版本推进(将 p26 引用更新为最新版本)
备注
- soroban 协议版本目录(当前为 p26)在重新生成时应更新为最新版本。
- 每个子系统摘要目标约 10KB;全系统摘要目标约 30KB。
- 所有摘要使用带
name:和description:字段的 YAML frontmatter。 - 目标是提供足够上下文,让 AI 智能体无需阅读全部源代码即可理解架构。