开发者文档

这一部分面向修改代码的人，描述 Etemenanki 工作区（内核 crate 和独立 app）以及 katana，细到具体的状态机、缓冲区和锁。

代码库一览

crate 或程序	职责
`etemenanki-concepts`	sans-I/O 代理模型：服务端协议核心、客户端 codec、单连接运行时、link 和 connector。不含任何协议实现。
`etemenanki-environment`	主机侧网络：共用同一套 socket 策略的 TCP、UDP 拨号器（外加可选的 QUIC 拨号器），以及路由模型。
`etemenanki-protocols`	所有协议和传输层：SOCKS、HTTP、Shadowsocks、Trojan、VLESS、VMess、Hysteria 2、WireGuard、TUN；TCP、TLS、WebSocket、gRPC；mux.cool 与 XUDP；DNS；嗅探。
`etemenanki-app`	独立代理：配置、入站与出站的构建、路由器组装、generation 与热重载。
`katana`	面板节点 agent，构建在前三个 crate 之上：面板客户端、节点生命周期、准入、流量计费、限速和审计。

依赖方向是单向的，从上层程序指向底层概念：

flowchart BT
  concepts["etemenanki-concepts"]
  environment["etemenanki-environment"]
  protocols["etemenanki-protocols"]
  app["etemenanki-app"]
  katana["katana"]
  environment --> concepts
  protocols --> environment
  app --> protocols
  katana --> protocols

每条箭头表示直接依赖；每个 crate 也会直接使用它下面更底层的 crate。katana 是独立的仓库，从 registry 引用固定版本的三个库 crate；app 则和它们在同一个 workspace 里一起构建。

本部分导航

架构总览工作区结构、一条连接从 accept 到关闭的全过程，以及设计原则。

concepts服务端协议核心、单连接运行时、客户端 codec、link 与网络类型。

environment拨号器、socket 策略与路由模型。

protocols公共基础、嗅探、DNS、传输层、mux 以及每一种协议。

app从 TOML 到运行中的流水线、入站服务、出站、热重载与各种上限。

katana面板客户端、节点管理器、准入、流量计费与计量。

测试代码如何测试，以及一次改动需要哪些测试。

贡献指南验证门槛、审阅规则与发布顺序。

页面的写法

每一页都尽量遵循同一个提纲：

职责：这个组件做什么，以及刻意留给别人做什么。
关键类型：代码里会遇到的 trait、struct 和函数，附签名。
数据流：字节、事件或请求如何流经它，通常画成 Mermaid 图。
不变量：什么必须始终成立，由哪个机制保证。
失败路径：错误、取消与关闭。
上限：缓冲区大小、超时和各种上限。
测试：哪些测试钉住了这些行为。

源码引用

代码仓库是私有的，所以这些页面不链接到仓库。代码用「仓库内路径 + 符号名」来指称，例如 concepts/src/core.rs → ProxyCoreDecode。不写行号，因为行号会变。

每页标题下的 源码文件 列出该页所描述的文件，以及最近一次核对时的版本。之后只要其中任何文件发生变化，该页就会被重新核对。