Codara

Codara 把会话、任务、子代理、权限、多 Agent 协作和 IM 渠道接入收进同一套 Bun + TypeScript 运行时。不是聊天壳，是可以直接运行、验证和扩展的 Agent 执行引擎。

架构

完整架构蓝图见 ARCHITECTURE.md

DDD 轻量分层，10 个限界上下文，严格单向依赖：

src/
├── core/              执行引擎（Agent Loop + Pipeline + Middleware）
├── capability/        领域能力（Skill · Task · Command）
├── durability/        持久化（Session · Checkpoint）
├── observability/     观测（Runtime Events · Lifecycle Hooks）
├── integration/       集成适配（Tool · MCP · Channel · Provider）
├── context/           上下文来源（Instructions · Prompts · Skills）
├── config/            配置管理
├── codara/            应用层（Runtime 装配 + API 门面）
├── gateway/           消息网关（IM 渠道统一接入）
├── cli/               终端 UI（Ink）
├── desktop/           桌面 UI（React + Tauri v2）
├── server/            HTTP/SSE 服务
├── bus/               通信基础设施
└── shared/            共享内核（跨上下文契约）

依赖方向： 展示层 → 应用层 → 领域层 → 基础设施层 → 共享内核

┌─ 展示层 ────────────────────────────────────────────┐
│  cli/  │  desktop/  │  server/  │  gateway/          │
└────────────────────┬────────────────────────────────┘
                     │
┌─ 应用层 ───────────┴────────────────────────────────┐
│  codara/ (assembly + facade + entrypoints)          │
└────────────────────┬────────────────────────────────┘
                     │
┌─ 领域层 ───────────┴────────────────────────────────┐
│  core/  │  capability/  │  durability/  │  observability/  │
└────────────────────┬────────────────────────────────┘
                     │
┌─ 基础设施层 ───────┴────────────────────────────────┐
│  integration/  │  context/  │  config/  │  bus/      │
└────────────────────┬────────────────────────────────┘
                     │
┌─ 共享内核 ─────────┴────────────────────────────────┐
│  shared/ (contracts + types + utils)                │
└─────────────────────────────────────────────────────┘

多端接入

本地

消息网关（Gateway）

通过 bun run dev:gateway 启动，统一接入 7 个 IM 渠道：

会话管理： 4 种 DM 作用域（main / per-peer / per-channel-peer / per-account-channel-peer），跨渠道身份链接（Identity Links），文件持久化 + idle/daily 重置策略。

配置：~/.codara/gateway.json

{
  "channels": {
    "telegram": {
      "enabled": true,
      "accounts": {
        "default": { "botToken": "$TELEGRAM_BOT_TOKEN" }
      }
    }
  },
  "session": {
    "dmScope": "per-channel-peer",
    "resetPolicy": { "mode": "idle", "idleMinutes": 120 }
  }
}

核心机制

Agent Loop

每个 Agent 运行 model → tools → model 循环。所有路径 Stream-First（AsyncGenerator），delegation 走统一 stream() 链路。

Middleware Pipeline — 6 个拦截点

Review

工具执行可被 Permission 中间件拦截 → 通过 ChannelRegistry 路由到对应交互通道 → 用户审批/拒绝 → 恢复执行。

支持 CLI 终端审批、Desktop 对话框、IM 按钮（7 渠道均支持）。

Task Delegation

• Task — 单代理派发。主 Agent spawn 子 Agent，stream 化执行，活动实时上报；需要并行时由主 Agent 调度多个 delegated subagents，而不是再引入第二套协作 runtime。

三层扩展体系

Skill（用户态能力包）    ← SKILL.md 发现 → skills middleware 注入
  ↓ 通过 middleware 注入
Hook（生命周期桥接）     ← 只能观测，不控制执行
  ↓ 通过 middleware 桥接
Middleware（第一扩展机制） ← 拦截、修改、放行、阻断

Session & Checkpoint

• Session — 会话元数据，支持恢复/归档
• Checkpoint — Agent 完整状态快照，原子写入，compact 压缩
• Lock — Advisory 文件锁（PID + 5min TTL stale 检测）

快速开始

bun install
bun run dev         # CLI 开发模式

常用命令

bun run dev           # CLI（watch）
bun run dev:gateway   # 消息网关（IM 渠道）
bun run dev:server    # HTTP/SSE 服务
bun run dev:desktop   # 桌面端
bun run test          # 测试（1450+ tests）
bun run typecheck     # 类型检查（0 errors）
bun run lint          # 代码规范（0 errors）
bun run build         # 构建

技术栈