mcpField
K
koko

koko

github.com/joelhooks开发6536 次安装1 天前更新
代码仓库

关于 koko

koko 是面向 Koko Elixir 项目的开发技能，供构建或调试其 BEAM Agent 的开发者使用。它涵盖 OTP 模式、架构决策，以及 Koko 与 joelclaw 分阶段、初期只读的集成方式。

主要功能

  1. 01GenServer 与监督器开发指引
  2. 02工作负载和事件处理器实现
  3. 03Redis 桥接约束与阶段
  4. 04架构变更前检查 ADR
  5. 05OTP 调试与影子结果对比

适用场景

  1. 01添加 Koko 工作负载或事件处理器
  2. 02排查 OTP 监督树和进程崩溃
  3. 03修改 Redis 事件集成
  4. 04将影子结果与 TypeScript 对比

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/joelhooks/joelclaw --skill koko

安装后在 Claude Code 中输入/koko确认已加载。

详细介绍

Koko 开发

在开发 Koko Elixir 项目时使用此技能——这是与 joelclaw 同驻 BEAM 的 Agent。

使用场景

  • 在 Koko 中构建新的 GenServer、监督器或事件处理器
  • 实现工作负载（健康脉冲、事件摘要、影子执行器）
  • 将 Koko 接入新的 Redis 通道或 joelclaw 事件
  • 调试 OTP 监督树或进程崩溃
  • 将 Koko 的影子结果与 TypeScript 对应实现进行比较

触发词：koko、elixir agent、beam、otp、shadow executor、koko workload、koko event、mix

项目位置

  • 仓库：~/Code/joelhooks/koko（github.com/joelhooks/koko）
  • 主机：Overlook（Mac Mini M4 Pro），可通过 ssh joel@panda 访问
  • AGENTS.md：完整背景信息位于仓库根目录

ADR 注意事项

实现前务必检查相关 ADR。 Koko 的架构由 ADR 驱动。

ADR标题状态URL
0114Elixir/BEAM/Jido 迁移proposedjoelclaw.com/adrs/0114-elixir-beam-jido-migration
0115Koko 项目章程proposedjoelclaw.com/adrs/0115-koko-project-charter
0116Redis 桥接协议proposedjoelclaw.com/adrs/0116-koko-redis-bridge-protocol
0117首批工作负载proposedjoelclaw.com/adrs/0117-koko-first-workloads
0118影子执行器proposedjoelclaw.com/adrs/0118-koko-shadow-executor

添加新工作负载前：查看 ADR-0117 中的工作负载计划，以及 ADR-0118 中的影子执行模式。

更改 Redis 集成前：查看 ADR-0116 中的桥接协议和阶段边界。

进行任何架构变更前：在 ~/Vault/docs/decisions/ 中提出或更新 ADR。

关键约束

  1. Koko 处于只读状态（第 1 阶段）。 仅作为 PubSub 观察者。不得清空 LPUSH 队列，也不得执行权威写入。
  2. 仅限影子结果。 写入 Redis 中的 joelclaw:koko:shadow:<function> 或本地文件。绝不写入 Typesense、Todoist、网关或任何生产状态。
  3. Koko 崩溃时，系统不会受到影响。 TypeScript 技术栈不依赖 Koko。
  4. Redis 位于 localhost:6379 ——Overlook 上的 k8s NodePort。

开发命令

# Run
cd ~/Code/joelhooks/koko
mix deps.get
mix run --no-halt

# Test
mix test

# Interactive
iex -S mix
Koko.events_seen()

# Format
mix format

# Remote (from another machine)
ssh joel@panda "cd ~/Code/joelhooks/koko && mix run --no-halt"

应遵循的 OTP 模式

  • 每项关注点使用一个 GenServer ——健康检查器、事件累加器和影子运行器应为独立进程
  • 监督器策略：除非进程相互耦合（此时使用 rest_for_one），否则使用 one_for_one
  • 在 handle_info 中对事件类型进行模式匹配 ——不要使用 if/else 链
  • 所有日志输出都使用 Logger.info("[koko]") 前缀
  • 尽早崩溃 ——让监督器负责恢复，不要围绕故障编写防御性代码

实现阶段

第 1 阶段：被动观察者（当前）
  • 通过 PubSub 订阅 joelclaw:gateway:events ✅
  • 记录并分类事件 ✅
  • 下一步：添加健康脉冲 GenServer（ADR-0117 中的工作负载 1）
第 2 阶段：专用通道
  • 为已认领的工作创建 joelclaw:koko:events
  • TypeScript 将事件分发给 Koko：LPUSH joelclaw:koko:events <payload>
  • Koko 将结果写入 joelclaw:koko:results
第 3 阶段：影子执行器
  • 将选定的 Inngest 函数镜像为 Koko GenServer
  • 使用相同输入并行执行，然后比较结果
  • 影子日志位于 joelclaw:koko:shadow:<function>
第 4 阶段：毕业
  • Koko 比 TypeScript 更可靠地处理某项工作负载
  • 连续 30 天无需人工干预
  • 开发体验令人愉快

评论

支持 Markdown