MBOpenClacky

使用 MoonBit 编程语言完全重写的 AI Agent CLI 工具。

项目介绍

MBOpenClacky 是开源项目 openclacky 的 MoonBit 完整重写版本，已实现原项目全部核心功能并扩展至商业可用级别。差分测试 P2~~P6 阶段（单元差分回归、e2e 剧本、BUG-0001~~0057 修复、FEATURE_MATRIX 矩阵残留对齐）已全部完成，28 份相关 spec 归档于 specs/completed/。

原始项目：clacky-ai/openclacky（Ruby）
本项目语言：MoonBit
完成度：~99%（后端 ~99%，Web 前端 ~95%，TUI ~95%，部署 ~110%）

核心能力

下表由 scripts/repo_stats.sh 机器生成（generate），并由 CI 以 check 模式校验——手改数字会 stale 即红。口径定义见脚本头部注释。

指标	数值
版本（moon.mod / cmd VERSION / tui / web 四处一致）	0.2.0
源代码文件（`.mbt`，lib+cmd，不含测试）	316
测试文件（`_wbtest.mbt` + `_test.mbt`）	240
源代码行数	105,921
测试行数	65,633
总行数	171,554
测试用例（`moon test --release`，本模块 scoped 口径；CI 该步不含 lib/mcp，另一步单独跑）	4074
包（lib 一级包 / cmd 入口 / `moon.pkg` 总数）	25 / 1 / 30
`pkg.generated.mbti`（git 入库）	32
Provider 预设	13
内置工具	14
默认 Skill	16
REST 路由注册（crescent，`lib/web/server.mbt`）	214（GET 86 / POST 86 / PATCH 15 / DELETE 18 / PUT 9）
`moon check`	0 errors / 0 warnings

原生二进制约 3.6 MB（单一 AOT 可执行文件，随构建配置浮动，不列为闸门指标）。

功能亮点

多 LLM 后端：OpenAI / Anthropic / DeepSeek / GLM 等 13 种 Provider 预设
MCP 协议：Stdio 与 HTTP（Streamable HTTP / SSE）传输 + JSON-RPC 2.0 + 虚拟 Skill 映射（HTTP 侧经本地 mock server 完成握手与 tools/list 往返）
6 平台 IM 渠道：飞书 / 企微 / Telegram / Discord / 钉钉 / 微信
Web 前端 SPA + REST API：暗色主题 + WebSocket 实时通信（token 级流式），默认端口 7071
多模态处理：PDF/DOCX/PPTX/XLSX 解析 + Vision OCR + 视频理解（FFmpeg 抽帧 + LLM Vision）
GEP 技能自进化：EvolutionEngine + SkillReflector + AutoCreator
Time Machine：文件快照与回滚
PTY 终端执行：真实交互式命令会话
TUI：Inline Scrolling 架构，行级重绘 + commit-scrollback（终端原生滚动）+ mizchi/signals 响应式状态（底层 moonbit-community/tty）

核心技术优势

相较原 Ruby 实现，MoonBit 重写版带来：

AOT 原生编译 — 单一可执行文件（~3.6MB），毫秒级启动，零运行时依赖
静态类型安全 — 代数数据类型、Checked Error、Option[T] 消除 nil 访问
struct + trait 现代架构 — 显式 trait 实现 + AnyTool 枚举分发，替代 Ruby mixin 隐式耦合
GEP 技能自进化系统 — 执行后反思 + 模式检测自动创建技能
moon 一体化工具链 — build/check/test/fmt 开箱即用

架构决策

会话持久化：JSON 文件 vs SQLite

经评估对比，本项目采用与原项目一致的 JSON 文件持久化方案，而非 SQLite：

维度	JSON 文件	SQLite
部署复杂度	零依赖，单文件即可运行	需链接 SQLite 库，增加二进制体积
可调试性	文本格式，可直接查看/编辑	二进制格式，需专用工具
并发需求	单用户 CLI 场景，无高并发	适合多进程/多线程并发写入
数据规模	会话数据量小（KB 级）	适合大数据量（MB+）
跨平台	纯文件操作，无平台差异	需处理不同平台 SQLite 兼容性
与原项目兼容	沿用同一套 JSON 会话文件格式。参考机上 32 个历史会话文件（含早期 Debug-repr 转储、旧 Option 序列化器写出的 `[x]` / `[[...]]` 形态）只读读取已验证：`--list` 与 `cmd inspect` 均可读，文件本身不被改写。上游 openclacky（Ruby）原始会话文件样本不在手，未做端到端比对；读取路径已放宽为容忍缺字段、数字时间戳等字段变体（见 known-gaps）	需额外迁移逻辑

结论：对于 AI Agent CLI 工具的单用户、低并发、小数据量场景，JSON 文件方案在简洁性、可调试性和零依赖方面优势明显，是更合适的选择。

快速开始

# 安装依赖
moon update

# 类型检查
moon check

# 构建（显式指定 cmd 包，避免 moon #1488 bug）
moon build --target native --release cmd

# 运行
moon run cmd --message "Hello"          # 非交互模式
./_build/native/release/build/hnlyxiaobing/MBOpenClacky/cmd/cmd.exe   # TUI 交互模式（release 产物路径）
moon run cmd -- server                     # Web 服务（端口 7071）

# 契约探针（退出码 / stdout 形状 / stderr 策略 + moon run 对比）
./_build/native/release/build/hnlyxiaobing/MBOpenClacky/cmd/cmd.exe selftest

# 会话日志离线回放（CLI/TUI/Web 三端会话均产 append-only JSONL；旧 JSON 会话为只读导入）
./_build/native/release/build/hnlyxiaobing/MBOpenClacky/cmd/cmd.exe inspect <session.jsonl>

# 界面效果场景回放（层 4，统一 eval 入口；--format text|json|markdown，报告落 _build/eval/）
./_build/native/release/build/hnlyxiaobing/MBOpenClacky/cmd/cmd.exe eval --tui test/scenarios/tui/
./_build/native/release/build/hnlyxiaobing/MBOpenClacky/cmd/cmd.exe eval --web test/scenarios/web/

# 确定性能力评测（离线 harness：3 任务 × 2 次重复，stdout 输出评分向量 JSON）
./_build/native/release/build/hnlyxiaobing/MBOpenClacky/cmd/cmd.exe eval --offline --repo .

# 用户旅程 E2E（层 9，代替日常手工验证：真实二进制 + mock 上游走 18 条端到端旅程——
# Web WS 聊天 9 / TUI 交互 3 / CLI 6；进程级沙箱隔离，三级看门狗永不挂起）
# 触发方式：先构建 release 产物，再跑 journey 子命令（journey 驱动的就是这个二进制）
moon build --target native --release cmd
./_build/native/release/build/hnlyxiaobing/MBOpenClacky/cmd/cmd.exe journey --repo .            # 全量 18 条
./_build/native/release/build/hnlyxiaobing/MBOpenClacky/cmd/cmd.exe journey --repo . --filter cli_ --verbose   # 只跑某面 + 逐步日志
# 退出码：0=全绿  1=产品红（≥1 旅程失败）  2=用法错  3=运行器坏（区分「产品问题」与「E2E 自身故障」）
# 失败自动落证据包到 _build/journey/<时间戳>/<场景>/（mock 请求原文 / WS 双向帧 / 子进程输出 / TUI 虚拟屏 / 工作区终态）
# 并 upsert 入库台账 docs/journey-failures.md；同场景转绿即自动移入「已修复」段（闭环无手工步骤）。
# 定时无人值守：本机已注册 Windows 计划任务「MBOpenClacky Journey E2E」（每日 08:30，先构建再跑）。
# 完整运行手册 / 场景 schema / 断言与占位符：test/journey/README.md；设计规格：specs/draft/2026-09-23_journey-e2e-runner.md

# 真模型能力评测（层 8，手动触发、不进 CI）：默认任务集 test/capability/tasks（10 任务 × 3 次重复），
# 报告写 docs/eval/<date>.md。需配置模型（MBOPENCLACKY_* / config.toml / DEEPSEEK_*），否则诚实 exit 1。
MBOPENCLACKY_API_KEY=... MBOPENCLACKY_BASE_URL=https://api.deepseek.com \
  MBOPENCLACKY_MODEL=deepseek-flash MBOPENCLACKY_ANTHROPIC_FORMAT=false \
  ./_build/native/release/build/hnlyxiaobing/MBOpenClacky/cmd/cmd.exe eval --live

# 性能基准（层 7，手动触发；场景在 test/benchmark/scenarios，结果写 _build/benchmark/results）
./_build/native/release/build/hnlyxiaobing/MBOpenClacky/cmd/cmd.exe benchmark --iterations 20 --warmup 5

# 真话台账校验（扫描段过期 / 命中项缺状态行 即失败；活跃缺口在 docs/known-gaps.md，已修复归档在 docs/resolved-gaps.md）
scripts/known_gaps.sh check

# 仓库数字闸门（README/AGENTS/project-status 的数字由脚本生成，stale 即失败）
scripts/repo_stats.sh check

# 测试（scoped 口径，与 CI 同范围；debug/release 均可跑）
# 必须显式限定本模块的包：裸 `moon test` 会按 moon.work 连 vendor/mbtpdf 一起跑
# （其自带文档测试失败，不属本仓回归面）。Windows 与 Linux 同一条命令。
moon test --release $(find lib cmd test -name moon.pkg | sed 's|/moon.pkg$||')

详细的环境要求、安装步骤、配置指南和故障排除，请参阅快速入门指南。

机器闸门与合规

本仓库把”对外承诺”变成可运行的检查，而不是文档里的说法：

闸门	命令	拦截
类型与警告	`moon check`（CI 固定 0 警告预算）	类型错误、新增警告
公共 API 冻结	`moon info` + `git diff --exit-code -- '**/pkg.generated.mbti'`	改了公共符号却没提交接口文件（数量见「当前规模」生成表）
CLI 契约	`<binary> selftest`	退出码 / stdout 形状 / stderr 干净度 / panic 泄漏；并对比 `moon run cmd`
真话台账	`scripts/known_gaps.sh check`	活跃台账（`docs/known-gaps.md`）与代码不一致
数字单一事实来源	`scripts/repo_stats.sh check`	README / AGENTS.md / project-status 的规模数字与机器统计不一致（含版本常量四处理一致性）
能力评测	`<binary> eval --offline`	确定性 tool_harness 的任务失败 / 不可重复（离线、无模型）
测试	`moon test --release`	回归（含协议往返 + 会话日志 DoD + harness 任务集）

未完成项（机器校验）：docs/known-gaps.md（活跃缺口） / docs/resolved-gaps.md（已修复归档）
测试体系分层与门禁（层 1-9）：docs/testing.md
AI 使用声明：docs/ai-usage.md　开源披露：NOTICE
协议叶子边界决策：ADR-0001

项目结构

MBOpenClacky/
├── cmd/                # CLI 入口
├── lib/                # 25 个库包
│   ├── agent/          # Agent 核心（ReAct 循环、会话、压缩、Time Machine）
│   ├── client/         # LLM API 客户端（3 协议、13 Provider）
│   ├── tool/           # 工具系统（14 个内置工具、PTY 终端）
│   ├── skill/          # 技能系统 + GEP 进化引擎
│   ├── extension/      # 扩展系统（Loader/Verifier/Packager/Scaffold/Marketplace + API 路由分发）
│   ├── mcp/            # MCP 协议（Stdio + HTTP/SSE 传输 + JSON-RPC 2.0）
│   ├── channel/        # 6 平台 IM 适配器
│   ├── web/            # Web 服务器（REST 路由注册数见上方机器生成表、WebSocket）
│   ├── i18n/           # 国际化（中英文翻译）
│   ├── tui/            # TUI 界面（行级重绘 + commit-scrollback + moonbit-community/tty）
│   ├── server/         # 运维（Cron、浏览器管理、备份、Git 面板）
│   ├── config/         # 配置系统（TOML、13 Provider）
│   ├── billing/        # 计费系统
│   ├── brand/          # 品牌配置 + AES-256-GCM 加密
│   ├── media/          # 媒体生成
│   ├── parser/         # 文档解析（PDF/DOCX/PPTX/XLSX）
│   ├── protocol/       # 协议层（引擎事件与 wire 词表）
│   ├── vision/         # Vision OCR
│   ├── pricing/        # 模型定价表
│   ├── message/        # 消息类型
│   ├── hook/           # Shell Hook 系统
│   ├── telemetry/      # 匿名遥测
│   ├── errors/         # 错误类型层次
│   ├── utils/          # 工具函数
│   └── zip/            # ZIP 压缩/解压
├── test/               # 测试体系层 1-9：差分 + e2e 剧本 + Eval 引擎/场景 + 基准 + 夹具（见 docs/testing.md）
├── assets/             # Agent 配置、技能、Web 前端
├── specs/              # Harness 方法论（模板 + 活跃 spec + 归档）
├── .github/            # CI/CD 工作流
└── docs/               # 项目文档

当前状态与已知问题

功能对比与完成度：项目状态文档
真话台账（机器校验的未完成项清单）：docs/known-gaps.md（活跃缺口） / docs/resolved-gaps.md（已修复归档） — 由 scripts/known_gaps.sh 扫描生成，CI 校验与代码一致
优化提升计划（对标上游，全部 WP 已闭环 + 下一步方向）：docs/improvement-execution-plan.md

开源协议

MIT License — 与上游 openclacky 保持兼容。详见 LICENSE。

致谢

特别感谢原项目 clacky-ai/openclacky 的作者与贡献者，他们的设计与实现是本重写工作的全部起点。