Agent 运行时 FloraAurella/athena-harness-demo

Athena Harness Demo

CI
License: MIT

Athena Harness Demo 是一个直接构建在 Cordis 和 AI SDK 之上的轻量、平台无关 Agent 运行时。它用于验证一种可组合的服务内核，覆盖模型循环、作用域化工具与提示词、追加写入的 Session，以及基于 JSONL 的持久化恢复。

[!IMPORTANT]
本项目是架构原型。API 和持久化格式未来可能发生变化，目前暂不发布到 npm。

项目简介

Athena Harness Demo 将 Cordis 根上下文的所有权交给宿主应用，同时提供一组聚焦的服务能力：

- 在同一个 Cordis 根上下文中运行多个相互隔离的 Agent；
- 每个模型 Step 显式调用一次 streamText()；
- 支持根级全局和 Agent 级作用域的工具、提示词注册；
- 为每个 Step 生成不可变的工具快照；
- 使用支持 TypeScript 声明合并、追加写入的 Session Event；
- 将 Session Event 确定性地投影为 AI SDK 模型消息；
- 支持由所有者控制的 Agent 释放，以及创建过程中的安全回滚；
- 支持 JSONL 持久化、严格恢复和中断 Turn 恢复。

本项目有意不提供 CLI、应用框架、兼容层或额外的模型 Provider 抽象。完整的架构说明和非目标请参阅设计文档。

环境要求

- Node.js 20 或更高版本
- Corepack
- Yarn 4

本地开发

git clone https://github.com/nazidada/athena-harness-demo.git
cd athena-harness-demo
corepack enable
yarn install --immutable
yarn typecheck
yarn test
yarn build

构建输出位于 dist/，不会提交到 Git 仓库。

基础组合方式

宿主应用负责创建 Cordis 上下文，并显式安装需要的服务：

import { Context } from 'cordis'
import {
AgentRegistry,
ModelSurface,
SessionStore,
SystemPrompt,
ToolRuntime,
} from '@yesimbot/athena-harness'
import { AgentLoop } from '@yesimbot/athena-harness/agent-loop'
import { JsonlPersistence } from '@yesimbot/athena-harness/persist/jsonl'

const ctx = new Context()

await ctx.plugin(SessionStore)
await ctx.plugin(ModelSurface)
await ctx.plugin(ToolRuntime)
await ctx.plugin(SystemPrompt)
await ctx.plugin(AgentRegistry)
await ctx.plugin(JsonlPersistence, { directory: './sessions' })
await ctx.plugin(AgentLoop)

创建 Agent 时传入任意 AI SDK LanguageModel，发送结构化的用户事件，并等待当前 Turn 完成：

const handle = await ctx.agents.create({
id: 'example-agent',
model,
maxSteps: 8,
})

handle.agent.send('user/message', {
role: 'user',
content: 'Inspect the project and summarize it.',
})

await handle.agent.whenIdle()
await handle.dispose()
await ctx.fiber.dispose()

本项目不会选择或配置具体的 AI Provider。创建或恢复 Agent 时，需要由调用方提供可用的模型实例。

注册工具和提示词

扩展使用普通的 Cordis 插件实现。注册内容归属于执行安装操作的 Fiber，并会在该 Fiber 释放时自动移除。

import { z } from 'zod'

const projectTools = Object.assign((pluginCtx: Context) => {
pluginCtx.tools.register('read_note', {
description: 'Read a note by name',
inputSchema: z.object({ name: z.string() }),
execute: async ({ name }) => loadNote(name),
})

pluginCtx.systemPrompt.registerSection(
'role',
'You are a careful project assistant.',
{ order: 10 },
)

pluginCtx.systemPrompt.registerContext(
'workspace',
() => Workspace: ${workspaceName},
{ order: 20 },
)
}, {
inject: ['tools', 'systemPrompt'] as const,
})

await ctx.plugin(projectTools)

工具按顺序执行。安装了持久化服务时，工具产生副作用之前，会先追加对应的执行意图并完成持久化检查点。

持久化与恢复 JsonlPersistence 为每个 Session 保存一个带版本信息的 JSONL 文件。恢复 Session 时，需要再次由调用方提供可用的模型实例：

const handle = await ctx.agents.resume({
id: 'example-agent',
model,
maxSteps: 8,
})

恢复过程会拒绝格式错误的 Header、非连续的 Event 序列、无效的生命周期轨迹、无效的 Model Surface 操作，以及缺少投影器的必需自定义 Event。如果进程在 Turn 执行过程中停止，恢复逻辑会记录未知的工具执行结果，并补充明确的中断 Step 和 Turn 结束事件。

项目结构

- src/ — 服务定义和实现
- src/agent-loop/ — 默认的手动 AI SDK Loop Provider
- src/persist/ — 持久化契约和 JSONL Provider
- test/ — 运行时测试和公共 API 类型测试
- docs/design.md — 已确认架构决策的源文档
- talks/ — 设计探索过程记录

当前状态与范围

Athena Harness Demo 当前面向 AI SDK v7 和上游 Cordis v4。项目不提供 YesImBot 或 Koishi 集成、旧数据迁移、Subagent、审批流水线、沙箱框架，也不提供顶层 Runtime 工厂。

JSONL 格式当前为版本 0。在稳定版本策略确定前，请将持久化数据视为实验性数据。

参与贡献

欢迎提交 Issue 和 Pull Request。提交变更前请先阅读贡献指南。安全问题请按照安全策略进行报告。

许可证

Athena Harness Demo 采用 MIT License 开源。