# 项目状态与上游对齐

> 更新日期：2026-10-14
> 对比基线：[clacky-ai/openclacky](https://github.com/clacky-ai/openclacky)（Ruby）。
> 本文给结论和边界；历史实现细节看 [CHANGELOG](CHANGELOG.md) 与 `specs/completed/`，逐行缺口看 [known-gaps](known-gaps.md)。

## 1. 当前结论

MBOpenClacky 已覆盖上游 Agent CLI 的主要用户面，并在部署、静态类型、会话日志和自动化测试方面做了扩展。项目不使用主观百分比表示完成度；实际边界以机器闸门和真话台账为准。

| 维度 | 当前状态 |
|---|---|
| 版本 | 0.3.0；`moon.mod` / `cmd` / TUI / Web 四处一致 |
| 正式目标 | native；wasm-gc 仅 `moon check` |
| Agent | ReAct、压缩、重试/回退、子代理、记忆、Todo、Time Machine、成本追踪 |
| 工具 | 14 个注册进 `AnyTool` 的内置工具；另有安全策略与 PTY 内部能力 |
| Skill | `assets/skills/` 16 个默认 Skill；扩展包另带 3 个 Skill |
| 扩展 | 10 个内置扩展清单；Loader/Verifier/Packager/Scaffold/Marketplace/Patch/API 贡献可用 |
| MCP | Stdio + Streamable HTTP/SSE；MCP server 子命令可用；能力面限 tools |
| 渠道 | 6 平台；send/receive 主路径已接线，平台不支持的编辑/撤回会明确报错 |
| Web | 214 个 crescent REST 路由 + WebSocket；原生 JS 前端；默认 7071 |
| 会话 | JSON 快照 + append-only JSONL；三端可 `cmd inspect`；旧格式只读兼容 |
| 测试 | 层 1-9 + Playwright Web E2E；CI 与本地命令口径见 [testing](testing.md) |

### 仓库规模

<!-- BEGIN: repo-stats (generated by scripts/repo_stats.sh; do not edit) -->
| 指标 | 数值 |
|------|------|
| 版本（moon.mod / cmd VERSION / tui / web 四处一致） | 0.3.0 |
| 源代码文件（`.mbt`，lib+cmd，不含测试） | 316 |
| 测试文件（`*_wbtest.mbt` + `*_test.mbt`） | 241 |
| 源代码行数 | 106,154 |
| 测试行数 | 65,741 |
| 总行数 | 171,895 |
| 测试用例（`moon test --release`，本模块 scoped 口径；CI 该步不含 lib/mcp，另一步单独跑） | 4076 |
| 包（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 |
<!-- END: repo-stats -->

## 2. 与上游的差异

| 维度 | openclacky | MBOpenClacky |
|---|---|---|
| 语言/运行时 | Ruby | MoonBit AOT native |
| 包管理 | Bundler/RubyGems | moon/mooncakes |
| 工具面 | 上游 16 项（含抽象/策略项） | 14 个实际注册工具；覆盖用户工具面，并增加记忆工具 |
| Skill | 上游默认目录 17 项 | 16 个默认 Skill + 扩展贡献 Skill |
| Web | Ruby 服务端 + JS 前端 | MoonBit 服务端 + 托管 fork JS 前端 |
| TUI | Rich UI/UI2 | Inline Scrolling + commit-scrollback |
| 会话 | JSON | JSON 快照 + JSONL 事件日志 |
| 部署 | 上游脚本/Homebrew | Docker Compose、systemd、logrotate、Windows 安装器 |

有意差异：Web 默认端口为 7071（上游 7070）；认证变量使用 `MBOPENCLACKY_WEB_API_KEY`；`web/ext_ui/` 是本项目新增面板。前端同步基线与补丁见 [web/UPSTREAM_SYNC.md](../web/UPSTREAM_SYNC.md) 和 [web/PATCHES.md](../web/PATCHES.md)。

## 3. 功能面核对

### 3.1 工具与能力

14 个默认注册工具为：`file_reader`、`write`、`edit`、`grep`、`glob`、`terminal`、`web_search`、`web_fetch`、`invoke_skill`、`memory_tool`、`todo_manager`、`ask_user`（兼容 `request_user_feedback`）、`trash_manager`、`browser`。

工具别名把常见 LLM 工具名映射到规范名。PTY 是 `terminal` 的底层会话能力，安全策略是执行审批层，二者不应重复计为独立注册工具。

### 3.2 Skill 与扩展

- `assets/skills/` 有 16 个默认 Skill。
- `assets/extensions/` 有 3 个 Skill：`ext-develop` 来自默认启用的 `ext-studio`；`meeting-summarizer` 与 `extend-openclacky` 随 `meeting`、`mb-extend` 发布，但这两个扩展默认关闭。
- 扩展贡献可注册 Agent、Skill、Panel、Hook、Patch 和 API route。运行期热加载扩展不能实现 MoonBit trait；命令式扩展行为使用 shell command。

### 3.3 渠道

| 平台 | 发送 | 编辑/撤回 | 接收 |
|---|---|---|---|
| 飞书 | REST send/upload/download/history | PATCH / DELETE | webhook |
| Telegram | Bot API | editMessageText / deleteMessage | `getUpdates` 长轮询 |
| Discord | REST | PATCH / DELETE | Gateway（含心跳/恢复） |
| 企业微信 | 应用消息 API | 平台不支持，明确报错 | webhook + Bot WebSocket |
| 钉钉 | webhook/API | 平台不支持，明确报错 | webhook + Stream Mode |
| 微信 | iLink send（AES-128-ECB） | 平台不支持，明确报错 | webhook |

六个平台共用 `~/.mbopenclacky/channels.json`，Web 面板、`channel-manager` Skill 与运行时读取同一配置源。

### 3.4 Web 与媒体

Web 后端使用 crescent，包含日志、错误信封、认证、超时、缓存控制和 CORS 中间件；WebSocket 负责 token 级流式和引擎事件。媒体端点已调用 `lib/media` 与 `lib/client` 的真实实现：

- `POST /api/media/image`
- `POST /api/media/video`
- `POST /api/media/audio/speech`
- `POST /api/media/audio/transcriptions`
- `POST /api/media/video/understand`

视频生成当前是同步执行；`GET /api/media/video/status` 会如实说明这一模型。

### 3.5 会话与持久化

会话采用 JSON 快照，而不是 SQLite：单用户、低并发、小数据量场景下，JSON 更容易调试、备份和保持旧文件兼容。每次运行同时追加 JSONL 引擎事件：

- CLI、TUI、Web 都会写 session log；
- 压缩以 `summary` 事件投影，不改写既有 JSONL 字节；
- `cmd inspect` 支持 `.jsonl` 与旧 `.json`；
- 旧 Option 包装和 Debug-repr 文件只读投影，不就地迁移。

## 4. 当前限制

机器扫描截至 2026-10-14 为 65 条 `open` + 1 条 `retracted`。类别分布：

| 类别 | 主要限制 |
|---|---|
| wasm | MCP stdio、PTY、浏览器进程等 wasm 回退；native 路径才完整 |
| brand | License/技能商店远端 HTTP、设备信息 FFI 等服务端集成未完成 |
| extension | 依赖自动解析、远程扩展下载、无 command 路由的回退契约 |
| telemetry | HTTP 上报、容器检测、SHA256 仍为占位 |
| web | 任务快照 diff/restore preview、worker 模式重启 |
| TUI/browser | 背景色探测、浏览器检测 FFI、无 MCP 时浏览器工具的诚实报错 |
| 评测 | 真模型任务集仍偏小，尚无与 Ruby 上游同参数的双侧对标 |

逐条位置、状态和交付物以 [known-gaps.md](known-gaps.md) 为准；已修复项在 [resolved-gaps.md](resolved-gaps.md)。

## 5. 下一步

1. 做 Ruby/MoonBit 双侧真模型对标，固定模型、参数和任务集。
2. 将真模型任务集从 10 条扩充到 20–30 条，并明确哪些指标可做趋势判断。
3. 按需推进运行时原语：类型化审批、子代理进程隔离、沙箱写范围、goal/plan/steer/job。
4. 只有在规格先行、对抗评审通过后，才扩大 wasm、品牌服务端或遥测范围。

详细工作流见 [improvement-execution-plan.md](improvement-execution-plan.md) 与 [specs/README.md](../specs/README.md)。