# Known Gaps（真话台账）

> **真话台账**：由 `scripts/known_gaps.sh` 扫描产品代码生成（`generate`），由 CI 以 `check` 模式校验——扫描段落必须与代码一致（stale 即红），且每条命中必有 curated 状态行。
>
> **纪律**：修复一条缺口 → 重跑 `generate` → 该条从扫描表消失 → 将对应 curated 行从本文移至 `docs/resolved-gaps.md` 并标记为 `fixed`（保留修复记录）。新增 TODO/stub → `generate` 后必须在 §台账 补行，否则 CI 红。
>
> 裸 `Err(` 不计为缺口：Err(...) 是 MoonBit 标准错误构造，裸扫会命中全仓所有合法错误返回；仅当同行携带 stub 短语时经由扫描模式命中（见下）。

## 状态说明

- `open`：真实缺口，已确认；除注明外均属本期范围外（范围冻结见 `docs/improvement-execution-plan.md` §2）
- `retracted`：撤回（误报或不再适用）

> 已修复条目（`fixed`）归档至 [`docs/resolved-gaps.md`](resolved-gaps.md)，不再参与本文的 CI 校验。

## 当前边界与环境说明（人工维护）

| 问题 | 现象 | 状态与处置 |
|---|---|---|
| 裸 `moon test` 不是验收命令 | `moon.work` 含 vendored workspace members，会连带运行依赖自身测试；部分测试在当前工具链上失败或触发 ICE | 本仓库只用 scoped `lib cmd test` 命令；CI 主步另排除 `lib/mcp` 并单独运行。依赖测试不是本仓回归面 |
| wasm-gc | tty/crescent/PTY/MCP/browser 等路径含 native FFI 或 wasm 回退 | native 是正式验收目标；wasm-gc 只跑 `moon check` |
| 真模型评测覆盖 | 离线层已进 CI，真模型层有 10 条任务，但任务集仍偏基础且随机 | `cmd eval --live` 已接线；下一步扩充到 20–30 条并与 Ruby 上游做同参数对标。单次全通过不代表模型能力强 |
| 上游 Ruby 会话样本 | 本地旧 JSON/Debug-repr 已只读兼容，但没有上游 Ruby 原始会话样本做端到端比对 | 只读投影已验证；上游兼容面仍待样本和双侧测试 |
| TUI 协议接入面 | Web/CLI 使用 wire 词表，TUI 直接消费引擎 `HookEvent` | 有意边界，见 ADR-0001；不要把 wire 投影丢字段的问题转成 TUI 回归 |
| 技能进化 UI/执行台账 | 进化 API 已可用，但面板无执行证据；运行期没有 SkillExecution 台账，`PostExecution` 无生产调用方 | 有意限制。没有真实证据时不提供假成功按钮；接台账是独立工作项 |

已解决的历史环境问题（Windows `lib/mcp` stdio 集成、Web JSONL、旧会话投影等）记录在 [CHANGELOG](CHANGELOG.md)、`specs/completed/` 和 [resolved-gaps](resolved-gaps.md)，不再重复列为当前缺口。
<!-- BEGIN: auto-scan (regenerated by scripts/known_gaps.sh; do not edit) -->

扫描范围：`lib/` + `cmd/` 产品代码（排除 `*_wbtest.mbt`/`*_test.mbt`）。模式：`TODO` `FIXME` `not implemented` `not yet` `placeholder` `stub`。裸 `Err(` 不计为缺口（MoonBit 标准错误构造，裸扫会命中全仓所有合法错误返回），仅当同行携带 stub 短语时经由上述模式命中。

当前命中 **66** 条（另有 118 条域术语命中被抑制，抑制规则及理由见 §抑制规则）。

| 位置 | 标记 | 摘要 |
|---|---|---|
| cmd/channel_scaffold.mbt:88 | stub | "///\|\n/// \{platform} channel adapter implementation.\npub(all) struct \{platform}_Adapter {\n  config : \{platform}_Config\n} derive(Debug |
| lib/agent/diagnostics.mbt:9 | stub | /// Write one diagnostic line to stderr (a newline is appended by the stub). |
| lib/agent/react.mbt:415 | not-yet | // here — not yet ported.) |
| lib/brand/crypto.mbt:215 | stub | // ---- WASM fallback stubs ---- |
| lib/brand/device.mbt:33 | TODO | /// TODO: Replace with FFI to GetComputerNameW / gethostname(). |
| lib/brand/device.mbt:47 | TODO | /// TODO: Replace with FFI to GetUserNameW / getpwuid(). |
| lib/brand/license.mbt:104 | stub | /// Activate license. HTTP call is stubbed. |
| lib/brand/license.mbt:129 | TODO | // TODO: HTTP POST /api/v1/licenses/activate |
| lib/brand/license.mbt:146 | TODO | // TODO: HTTP POST /api/v1/licenses/deactivate |
| lib/brand/license.mbt:166 | stub | /// Send heartbeat. HTTP call is stubbed. |
| lib/brand/license.mbt:187 | TODO | // TODO: HTTP POST /api/v1/licenses/heartbeat |
| lib/brand/skill_manager.mbt:327 | TODO | // TODO: HTTP GET /api/v1/skills/download?name=<name> |
| lib/brand/skill_manager.mbt:328 | stub | Err("HTTP client not available (stub)") |
| lib/brand/skill_manager.mbt:342 | TODO | // TODO: 实际解密逻辑（XOR 占位） |
| lib/brand/skill_manager.mbt:364 | TODO | // TODO: 实际远程版本检查逻辑 |
| lib/brand/skill_manager.mbt:389 | TODO | // TODO: HTTP GET /api/v1/skills/available |
| lib/brand/skill_manager.mbt:390 | stub | Err("HTTP client not available (stub)") |
| lib/brand/skill_manager.mbt:397 | TODO | // TODO: HTTP GET /api/v1/skills/available (raw JSON) |
| lib/brand/skill_manager.mbt:406 | TODO | // TODO: HTTP GET /api/v1/skills/<name> |
| lib/brand/skill_manager.mbt:407 | stub | Err("HTTP client not available (stub)") |
| lib/brand/skill_manager.mbt:530 | TODO | // TODO: 标记技能为启用状态 |
| lib/brand/skill_manager.mbt:540 | TODO | // TODO: 标记技能为禁用状态 |
| lib/brand/skill_manager.mbt:550 | TODO | // TODO: 查询技能启用状态 |
| lib/client/client.mbt:15 | stub | ///\| synchronous stubs that build requests and parse responses using |
| lib/extension/verifier.mbt:159 | not-yet | /// Validate dependencies. MVP: just warn that automatic resolution is not yet implemented. |
| lib/mcp/stdio_transport.mbt:35 | stub | /// (WASM stub - process spawning not supported). |
| lib/mcp/stdio_transport.mbt:518 | stub | // ── WASM fallback stubs ──────────────────────────────────────────────────── |
| lib/mcp/stdio_transport.mbt:521 | stub | /// Start the child process (WASM stub - not supported). |
| lib/mcp/stdio_transport.mbt:532 | stub | /// Stop the child process (WASM stub - no-op). |
| lib/mcp/stdio_transport.mbt:539 | stub | /// Send a JSON-RPC message (WASM stub - not supported). |
| lib/mcp/stdio_transport.mbt:550 | stub | /// Send a JSON-RPC request (WASM stub - not supported). |
| lib/server/browser_jsonrpc.mbt:176 | stub | // ── WASM fallback stubs ──────────────────────────────────────────────────── |
| lib/server/browser_jsonrpc.mbt:179 | stub | /// Send a JSON-RPC request (WASM stub — not supported). |
| lib/server/browser_jsonrpc.mbt:192 | stub | /// Send a JSON-RPC notification (WASM stub — not supported). |
| lib/server/browser_jsonrpc.mbt:205 | stub | /// Perform MCP initialize handshake (WASM stub — not supported). |
| lib/server/browser_process.mbt:3 | stub | /// Uses `@async/process` for process management; falls back to stubs on wasm targets. |
| lib/server/browser_process.mbt:19 | stub | /// Wraps a chrome-devtools-mcp child process (WASM stub — not supported). |
| lib/server/browser_process.mbt:155 | stub | // ── WASM fallback stubs ──────────────────────────────────────────────────── |
| lib/server/browser_process.mbt:158 | stub | /// Spawn the MCP daemon process (WASM stub — not supported). |
| lib/server/browser_process.mbt:170 | stub | /// Write a line to process stdin (WASM stub — not supported). |
| lib/server/browser_process.mbt:181 | stub | /// Read a line from process stdout (WASM stub — not supported). |
| lib/server/browser_process.mbt:190 | stub | /// Check if process is alive (WASM stub — always false). |
| lib/server/browser_process.mbt:197 | stub | /// Kill the process (WASM stub — no-op). |
| lib/telemetry/telemetry.mbt:110 | TODO,placeholder | // HTTP POST (placeholder: TODO FFI, fire-and-forget background) |
| lib/telemetry/telemetry.mbt:127 | placeholder | // Check for Docker indicators (placeholder) |
| lib/telemetry/telemetry.mbt:146 | placeholder | // Simple deterministic hash (placeholder for SHA256) |
| lib/tool/browser.mbt:483 | stub | /// Falls back to a stub error message when MCP is not connected. |
| lib/tool/pty_session_wasm.mbt:6 | stub | /// wasm stub of execute_command_sync, which reports failure (-1). |
| lib/tool/pty_session_wasm.mbt:10 | stub | /// (stubbed) synchronous executor. |
| lib/tool/registry.mbt:59 | not-yet | // Other tool aliases (not yet implemented, but registered for future use) |
| lib/tui/theme.mbt:155 | stub | /// Currently returns `false` (dark background assumed). This stub can |
| lib/tui/todo_area.mbt:4 | stub | /// Phase 0 stub: keeps the struct and data methods, removes onebit-tui |
| lib/utils/browser_detector.mbt:140 | TODO | /// Detect installed browsers (TODO: FFI needed for filesystem scan). |
| lib/utils/browser_detector.mbt:142 | TODO | // TODO: implement via FFI filesystem scan |
| lib/utils/epipe_safe_io.mbt:20 | stub | /// Safe write to stdout. In wasm-gc target this is a stub that always succeeds. |
| lib/web/ext_dispatcher.mbt:7 | stub | /// temporary body file. When `command` is empty, it falls back to a stub |
| lib/web/ext_dispatcher.mbt:143 | stub | " (stub)" |
| lib/web/ext_dispatcher.mbt:427 | stub | /// If `command` is empty, the handler returns a stub response and logs a warning. |
| lib/web/ext_dispatcher.mbt:446 | stub | "[ExtensionDispatcher]   WARNING: route \{name}\{route_path} (\{handler_name}) has no command — returning stub", |
| lib/web/ext_dispatcher.mbt:469 | stub | let body = "{\"extension\":\"\{name}\",\"handler\":\"\{handler_name}\",\"timeout_ms\":\{timeout},\"status\":\"stub\"}" |
| lib/web/ext_loader.mbt:14 | stub | /// Shell command to execute for this route (empty = stub fallback) |
| lib/web/handlers_extra.mbt:13 | not-yet | /// capability not yet exposed by the git_exec layer, so it is deferred; |
| lib/web/handlers_extra.mbt:1189 | stub | /// Returns a stub response; full task-snapshot diff requires deeper infra. |
| lib/web/handlers_extra.mbt:1215 | stub | /// POST /api/sessions/:id/time_machine/:task_id/restore_preview — restore preview stub. |
| lib/web/handlers_store.mbt:225 | not-yet | "Remote extension download is not yet supported. Install from local path instead.", |
| lib/web/handlers_version.mbt:287 | not-yet | message: "Restart signal accepted. Standalone mode requires manual restart; worker mode is not yet wired.", |

<!-- END: auto-scan -->


## 抑制规则（域术语，非缺口）

以下模式命中的标记为合法领域词汇、设计行为或历史引用，不计入台账（规则实现见 `scripts/known_gaps.sh` 的 `SUPPRESSIONS`）：

| 模式 | 理由 |
|---|---|
| `lib/tui/**` 的 placeholder | TUI 输入框提示文本与 `[#N Paste Text]` 粘贴折叠是产品功能术语 |
| template_processor / i18n / message / format_* 的 placeholder | 占位符替换/修复是这些模块的功能本身 |
| pty / pty_marker 的 placeholder | PTY 标记协议的 `%s` printf 术语 |
| llm_caller / image_inject / react / default_profiles / tool_executor 的 placeholder | 流式 `"{}"` 截断信号、无视觉模型文本占位等设计行为 |
| todo.mbt / tool_executor.mbt 的 TODO | todo 管理功能的 UI 文案与提醒注入逻辑 |
| `stubfix-NN` | 历史规格流程引用（stubfix 系列 spec），非未完成标记 |
| not yet persisted / does not yet exist / has not yet completed | 运行时状态描述，非缺口 |
| pty_stubs.c / time_stub.c / tool_stubs.c / browser_popen.c / console_cp_ext | 真实 C 辅助文件（实现本体，非占位） |
| feishu_message_parser 的 placeholder | 飞书富文本 img/at 占位是消息格式术语 |

## 台账（curated）

<!-- BEGIN: curation -->

| 位置 | 状态 | 交付物 | 说明 |
|---|---|---|---|
| cmd/channel_scaffold.mbt:88 | open | 范围外（channel 脚手架） | 脚手架模板生成的适配器为有意起点代码 |
| lib/agent/react.mbt:415 | open | 范围外（vision） | 无视觉模型时 Ruby 的 OCR 回退未移植 |
| lib/agent/diagnostics.mbt:9 | retracted | 误报（域术语） | 注释里的 "stub" 指实现 stderr 路由的 **C stub 本体**（`stderr_stub.c` 的 `mbopenclacky_write_stderr`，由 `write_diagnostic` 调用），属实现本体而非占位——与 `pty_stubs.c`/`time_stub.c` 同类。建议后续并入 §抑制规则 的 C 辅助文件族 |
| lib/brand/crypto.mbt:215 | open | 范围外（brand） | 品牌服务端 HTTP 调用为 stub（激活/心跳/技能商店） |
| lib/brand/device.mbt:33 | open | 范围外（brand） | 品牌服务端 HTTP 调用为 stub（激活/心跳/技能商店） |
| lib/brand/device.mbt:47 | open | 范围外（brand） | 品牌服务端 HTTP 调用为 stub（激活/心跳/技能商店） |
| lib/brand/license.mbt:104 | open | 范围外（brand） | 品牌服务端 HTTP 调用为 stub（激活/心跳/技能商店） |
| lib/brand/license.mbt:129 | open | 范围外（brand） | 品牌服务端 HTTP 调用为 stub（激活/心跳/技能商店） |
| lib/brand/license.mbt:146 | open | 范围外（brand） | 品牌服务端 HTTP 调用为 stub（激活/心跳/技能商店） |
| lib/brand/license.mbt:166 | open | 范围外（brand） | 品牌服务端 HTTP 调用为 stub（激活/心跳/技能商店） |
| lib/brand/license.mbt:187 | open | 范围外（brand） | 品牌服务端 HTTP 调用为 stub（激活/心跳/技能商店） |
| lib/brand/skill_manager.mbt:327 | open | 范围外（brand） | 品牌服务端 HTTP 调用为 stub（激活/心跳/技能商店） |
| lib/brand/skill_manager.mbt:328 | open | 范围外（brand） | 品牌服务端 HTTP 调用为 stub（激活/心跳/技能商店） |
| lib/brand/skill_manager.mbt:342 | open | 范围外（brand） | 品牌服务端 HTTP 调用为 stub（激活/心跳/技能商店） |
| lib/brand/skill_manager.mbt:364 | open | 范围外（brand） | 品牌服务端 HTTP 调用为 stub（激活/心跳/技能商店） |
| lib/brand/skill_manager.mbt:389 | open | 范围外（brand） | 品牌服务端 HTTP 调用为 stub（激活/心跳/技能商店） |
| lib/brand/skill_manager.mbt:390 | open | 范围外（brand） | 品牌服务端 HTTP 调用为 stub（激活/心跳/技能商店） |
| lib/brand/skill_manager.mbt:397 | open | 范围外（brand） | 品牌服务端 HTTP 调用为 stub（激活/心跳/技能商店） |
| lib/brand/skill_manager.mbt:406 | open | 范围外（brand） | 品牌服务端 HTTP 调用为 stub（激活/心跳/技能商店） |
| lib/brand/skill_manager.mbt:407 | open | 范围外（brand） | 品牌服务端 HTTP 调用为 stub（激活/心跳/技能商店） |
| lib/brand/skill_manager.mbt:530 | open | 范围外（brand） | 品牌服务端 HTTP 调用为 stub（激活/心跳/技能商店） |
| lib/brand/skill_manager.mbt:540 | open | 范围外（brand） | 品牌服务端 HTTP 调用为 stub（激活/心跳/技能商店） |
| lib/brand/skill_manager.mbt:550 | open | 范围外（brand） | 品牌服务端 HTTP 调用为 stub（激活/心跳/技能商店） |
| lib/client/client.mbt:15 | open | 范围外（client） | 注释疑似过时：S-FFI-06 已迁移 @async/http，需更新注释 |
| lib/extension/verifier.mbt:159 | open | 范围外（extension） | 依赖自动解析未实现，仅警告 |
| lib/mcp/stdio_transport.mbt:35 | open | 范围外（wasm） | wasm 目标回退 stub（native 路径真实实现） |
| lib/mcp/stdio_transport.mbt:518 | open | 范围外（wasm） | wasm 目标回退 stub（native 路径真实实现） |
| lib/mcp/stdio_transport.mbt:521 | open | 范围外（wasm） | wasm 目标回退 stub（native 路径真实实现） |
| lib/mcp/stdio_transport.mbt:532 | open | 范围外（wasm） | wasm 目标回退 stub（native 路径真实实现） |
| lib/mcp/stdio_transport.mbt:539 | open | 范围外（wasm） | wasm 目标回退 stub（native 路径真实实现） |
| lib/mcp/stdio_transport.mbt:550 | open | 范围外（wasm） | wasm 目标回退 stub（native 路径真实实现） |
| lib/server/browser_jsonrpc.mbt:176 | open | 范围外（wasm） | wasm 目标回退 stub（native 路径真实实现） |
| lib/server/browser_jsonrpc.mbt:179 | open | 范围外（wasm） | wasm 目标回退 stub（native 路径真实实现） |
| lib/server/browser_jsonrpc.mbt:192 | open | 范围外（wasm） | wasm 目标回退 stub（native 路径真实实现） |
| lib/server/browser_jsonrpc.mbt:205 | open | 范围外（wasm） | wasm 目标回退 stub（native 路径真实实现） |
| lib/server/browser_process.mbt:3 | open | 范围外（wasm） | wasm 目标回退 stub（native 路径真实实现） |
| lib/server/browser_process.mbt:19 | open | 范围外（wasm） | wasm 目标回退 stub（native 路径真实实现） |
| lib/server/browser_process.mbt:155 | open | 范围外（wasm） | wasm 目标回退 stub（native 路径真实实现） |
| lib/server/browser_process.mbt:158 | open | 范围外（wasm） | wasm 目标回退 stub（native 路径真实实现） |
| lib/server/browser_process.mbt:170 | open | 范围外（wasm） | wasm 目标回退 stub（native 路径真实实现） |
| lib/server/browser_process.mbt:181 | open | 范围外（wasm） | wasm 目标回退 stub（native 路径真实实现） |
| lib/server/browser_process.mbt:190 | open | 范围外（wasm） | wasm 目标回退 stub（native 路径真实实现） |
| lib/server/browser_process.mbt:197 | open | 范围外（wasm） | wasm 目标回退 stub（native 路径真实实现） |
| lib/telemetry/telemetry.mbt:110 | open | 范围外（telemetry） | HTTP POST/容器检测/SHA256 为占位 |
| lib/telemetry/telemetry.mbt:127 | open | 范围外（telemetry） | HTTP POST/容器检测/SHA256 为占位 |
| lib/telemetry/telemetry.mbt:146 | open | 范围外（telemetry） | HTTP POST/容器检测/SHA256 为占位 |
| lib/tool/browser.mbt:483 | open | 范围外（browser 工具） | MCP 未连接时的回退错误消息（设计行为：无 MCP 则无法调用浏览器工具，诚实报错） |
| lib/tool/pty_session_wasm.mbt:6 | open | 范围外（wasm） | wasm 目标回退 stub（native 路径真实实现） |
| lib/tool/pty_session_wasm.mbt:10 | open | 范围外（wasm） | wasm 目标回退 stub（native 路径真实实现） |
| lib/tool/registry.mbt:59 | open | 范围外（tool 别名） | 部分别名注册但未实现 |
| lib/tui/theme.mbt:155 | open | 范围外（TUI） | 终端背景色检测固定为深色 |
| lib/tui/todo_area.mbt:4 | open | 范围外（TUI） | Phase 0 占位（结构保留） |
| lib/utils/browser_detector.mbt:140 | open | 范围外（browser 运维） | 浏览器检测 FFI 未实现 |
| lib/utils/browser_detector.mbt:142 | open | 范围外（browser 运维） | 浏览器检测 FFI 未实现 |
| lib/utils/epipe_safe_io.mbt:20 | open | 范围外（wasm） | wasm 目标回退 stub |
| lib/web/ext_dispatcher.mbt:7 | open | 范围外（extension） | 无 command 的扩展路由返回 stub 响应（已文档化的回退契约） |
| lib/web/ext_dispatcher.mbt:143 | open | 范围外（extension） | 无 command 的扩展路由返回 stub 响应（已文档化的回退契约） |
| lib/web/ext_dispatcher.mbt:427 | open | 范围外（extension） | 无 command 的扩展路由返回 stub 响应（已文档化的回退契约） |
| lib/web/ext_dispatcher.mbt:446 | open | 范围外（extension） | 无 command 的扩展路由返回 stub 响应（已文档化的回退契约） |
| lib/web/ext_dispatcher.mbt:469 | open | 范围外（extension） | 无 command 的扩展路由返回 stub 响应（已文档化的回退契约） |
| lib/web/ext_loader.mbt:14 | open | 范围外（extension） | 无 command 的扩展路由返回 stub 响应（已文档化的回退契约） |
| lib/web/handlers_extra.mbt:13 | open | 范围外（web） | 任务快照 diff / restore_preview 为 stub |
| lib/web/handlers_extra.mbt:1189 | open | 范围外（web） | 任务快照 diff / restore_preview 为 stub |
| lib/web/handlers_extra.mbt:1215 | open | 范围外（web） | 任务快照 diff / restore_preview 为 stub |
| lib/web/handlers_store.mbt:225 | open | 范围外（extension） | 远程扩展下载不支持（提示本地安装） |
| lib/web/handlers_version.mbt:287 | open | 范围外（web） | worker 模式重启未接线 |

<!-- END: curation -->