harry-ma-qiang/tenon

Tenon

Tenon 是一个用于在 BEAM 上组合长期运行的智能体系统的微内核。该内核
是一个 Erlang 模块：一个插件、服务和钩子的注册表，具备生命周期、依赖
门控、事件分发和效果处置，外加一个线协议，使插件可以是
任何语言的进程。其他一切——配置加载器、YAML 方言、DSH
桥接、语言 SDK、CLI——都是内核之外的插件或调用者。

一个运行中的系统是一棵纤程树。每个纤程拥有一个插件实例。插件
发布服务并注册钩子；VM 外的插件使用线协议（4 字节
长度 + JSON 帧，位于 fd 3/4 上）通信，并通过句柄传递批量数据，绝不作为帧。当
一个纤程死亡时，无论是干净地还是暴力地，它注册的任何东西都不会存活。

设计参考：Cordis（MIT），见 NOTICE。决策、阶段计划和状态：NOTES.md。

状态：P4 完成（P4.0-4.8；P4.3 热段有意推迟到 P5），于 2026-08-20 独立 QA：
所有门禁通过（beam 51，Rust 单元测试 101 + P4 集成门禁），在单文件发布二进制上
用真实模型进行了端到端验证（bus/kv/timer、tenon run、ingress、webhook、MCP
双向、备份/恢复重放、tenon doctor），发现并修复了五个 P4.4 环境隔离缺陷，
密钥扫描干净。性能远在每项 RFC 预算之内（bus 扇出 282k msg/s，
publish->subscriber p99 1.3 µs；在 1M 事件下查询文本 p99 0.48 ms，扫描 p99 70 ms）。证据和
如何审查：REVIEW-P4.md。P3 的早期通过：REVIEW-P3.md。下一步：P5 内存 + 导航器。

布局

| 路径 | 内容 | 语言 |
|---|---|---|
| kernel/ | 原子内核，src/tenon.erl，零依赖 | Erlang |
| loader/ | 配置树插件：yml 层、补丁、组、DSH 折叠 | Elixir |
| cli/ | tenon escript：start / dump / check | Elixir |
| beam/ | tenon_beam：节点发布、链接 + 守护插件 | Elixir |
| rs/ | tenon 二进制和裸骨：基础、存储、沙箱、角色 | Rust |
| sdk/ | 线协议 SDK py/、ts/、rs/ + test/ 一致性套件 | Python、TS、Rust |
| bridge/dsh/ | tenon-bridge：整个 DeepSeek Harness 作为一个插件 | TypeScript |
| plugins/term/ | tenon-term：进程运行器，完整的句柄示例 | Rust |
| playground/ | 临时插件和一个 DSH home，gitignored | — |

快速开始

一个文件。tenon 是一个单一二进制文件，包含整个 BEAM 发布——ERTS、内核、加载器、
守护和网关——作为有效载荷嵌入，并在首次运行时解压到 ~/.tenon/erts/。
使用它无需安装任何其他东西：不需要 Erlang，不需要 Elixir，不需要
容器引擎（会自动检测沙箱后端，裸骨在没有沙箱的情况下也能启动）。

curl -fsSLO https://github.com//tenon/releases/latest/download/tenon-linux-x86_64
sha256sum -c tenon-linux-x86_64.sha256 && chmod +x tenon-linux-x86_64 && mv tenon-linux-x86_64 ~/bin/tenon

tenon start                       # 基础 + 守护节点 G + 根环境
tenon status                      # 哪些在运行、使用哪个沙箱后端、哪个版本
tenon run "summarise this repo"   # 一个任务，从会话日志中流式输出
tenon attach --ui                 # 内置的 ASCII UI
tenon stop

先让它指向一个模型 —— ~/.tenon/profiles/root/harness.yml 保存了提供方、模型，以及你的密钥所在环境变量的名称；密钥永远不会进入沙箱。rs/README.md 是主目录布局、角色和沙箱后端的参考文档，deploy/README.md 则介绍了如何在 systemd 或 launchd 下运行它。

要自行构建该二进制文件，或者参与 Tenon 的开发：

scripts/build-release.sh --verify     # -> dist/tenon-- + .sha256

为此以及以下所有内容所需的工具链：OTP 27 和 Elixir 1.18
（mise use -g erlang@27 elixir@1.18-otp-27）外加一个稳定的 Rust 工具链；node 22+ 搭配
pnpm 用于 TypeScript 部分，python3 用于 sdk/py。仅内核本身只需要前一对。

cd cli && mix escript.build          # -> cli/tenon，即下面的配置树 CLI

从配置树运行一个 python 插件。两个文件，均相对于 cli/：
yaml
demo/cordis.yml
- id: calc
name: py:calculator

demo/registry.yml
"py:calculator":
cmd: /usr/bin/python3
args: ["../playground/plugins/math_calculator.py"]

./tenon check demo/cordis.yml --registry demo/registry.yml   # 任何错误行都会以退出码 1 退出
./tenon dump  demo/cordis.yml --registry demo/registry.yml   # 行和解析后的类型
./tenon start demo/cordis.yml --registry demo/registry.yml   # 挂载并保持运行

start 会打印树并保持运行：SIGHUP 重新读取各层并应用差异，
SIGTERM 卸载并停止。通过添加 @deepseek-ai/dsh- 行并将 collapse 指向一个 DSH 检出，即可将 DSH 作为单个插件运行：

./tenon start demo/cordis.yml --dsh-home ~/.dsh --dsh-root ../../deepseek-harness \
--dsh-bridge ../bridge/dsh/dist/plugin.js

该命令行的前提条件：一个已完成 pnpm install、pnpm run build:lib:host
和 build:lib:client 的 DSH 检出，以及 cd bridge/dsh && pnpm install && pnpm run build。

DSH 兼容性

L1 — 配置文件。 cordis.yml、cordis.patch.yml、profiles 和 bundles
可原样接受，并组合成同一棵树（loader/）。
* L2 — TS 插件。 DSH 插件无需修改即可在单个 Node 进程中的真实 Cordis 上运行，
作为一个 Tenon fiber 挂载（bridge/dsh/）。
* L3 — 共享总线。 选定的 DSH 服务和事件通过
manifest 镜像到 Tenon 总线上，因此任何语言的插件都可以拒绝 DSH 工具调用。

门禁

每次提交，在你所触及的每个项目中：

| 项目 | 门禁 |
|---|---|
| kernel/ | mix compile（erlc 警告视为错误）、mix format --check-formatted、mix test |
| loader/、cli/ | 同上，外加 mix credo --strict |
| sdk/test/、bridge/dsh/test/ | mix test |
| beam/ | loader 门禁，外加 MIX_ENV=prod mix release |
| rs/ | cargo build --release、cargo clippy --all-targets --all-features -- -D warnings、cargo fmt --check、cargo test --all-features（需设置 TENON_RELEASE_DIR；对抗性测试套件单独运行） |
| sdk/rs/、plugins/term/ | cargo build --release、cargo clippy --all-targets -- -D warnings、cargo fmt --check |
| sdk/ts/、bridge/dsh/ | pnpm exec tsc --noEmit |

每次推送和拉取请求都会运行相同的门禁（.github/workflows/ci.yml）；v* 标签会构建并发布适用于 linux-x86_64、linux-aarch64 和 macos-arm64 的单一二进制文件（.github/workflows/release.yml）。

面向智能体和人类的编码规则：AGENTS.md。

AI 自我进化

Tenon 有意保持小巧：一个机器可以阅读、理解并改进的内核。为了验证这一点，一个现成的 CLI 编码智能体被放开——在沙箱中、限速并全程审计——从源码阅读内核并提出改进，而从未接触真实代码树。仅通过阅读源码，它发现了内核中一个真实的、未修补的拒绝服务漏洞（通过线路提供的字符串导致原子表耗尽），以及消息总线中一个真实的规范与实现偏差；两者都经过人工验证。完整的记录、方法、结论和可复现性说明：docs/ai-self-evolution.md。

许可证

MIT，参见 LICENSE。Tenon 是 Cordis 内核概念的功能性移植；此处未复制或再分发任何 Cordis 源代码，参见 NOTICE。