Gap Analysis: DARE example CLI vs Claude Code/Codex CLI（可集成性差距）

[zts212653]

背景

在调研 DARE 接入外部编排平台（类似 Cat Café）时，我们发现 DARE 的 example CLI（examples/06-dare-coding-agent-mcp/cli.py）与 Claude Code / Codex CLI 这类“可被宿主系统稳定编排”的 CLI 存在接口层 gap。

这不是在否定 DARE 的能力（A2A 路径已经可行），而是聚焦在：

• 如果把 DARE example CLI 当作“可嵌入的外部 Agent CLI”
• 目前和主流 CLI 在“可观测 + 可控制 + 可自动化”上的差异

---

关键 gap（对比 Claude Code / Codex CLI）

维度	Claude Code / Codex CLI（集成友好）	DARE example CLI 现状	影响
输出协议	提供稳定 machine-readable 流（stream-json / --json）	以 print 人类可读文案为主（[INFO]/[WARN]/[OK]），无稳定事件 schema	宿主很难可靠解析生命周期、工具事件、审批状态
控制面	宿主可通过 CLI flags / structured input 控制行为	审批/MCP 控制依赖 CLI 内部命令环（/approvals ...、/mcp ...）	运行中外部编排很难自动化接管
输入模型	易于“非交互式编排”	主循环依赖 input("dare> ") + slash 命令解析	需要伪终端/人工输入，不适合 server-to-server 调度
审批接口	常有外部可调用接口或稳定协议面	审批 action 通过进程内 DirectClientChannel + TransportEnvelope 调用	外部系统无法直接复用审批能力（需深度嵌入 Python 进程）

---

代码证据（当前 example CLI）

1. 交互输入主循环依赖 input("dare> ")

   • examples/06-dare-coding-agent-mcp/cli.py:991

2. 输出主要是人类可读 print(...)

   • examples/06-dare-coding-agent-mcp/cli.py:148（CLIDisplay）

3. 审批命令通过内部 Action envelope 调用

   • examples/06-dare-coding-agent-mcp/cli.py:538（_invoke_approval_action）
   • examples/06-dare-coding-agent-mcp/cli.py:544-546（TransportEnvelope + EnvelopeKind.ACTION）

4. 运行中控制通过 slash 命令（非结构化控制面）

   • examples/06-dare-coding-agent-mcp/cli.py:798（/approvals ... /mcp ...）

---

建议（最小改造，不破坏现有 UX）

Phase 1（P1，低风险）

新增 --output-format ndjson（默认保持现状）

• 事件建议：
  • session.started
  • model.response
  • tool.invoke
  • tool.result
  • approval.pending
  • approval.resolved
  • task.completed / task.failed

这样外部宿主至少可以稳定消费事件流。

Phase 2（P1）

新增结构化控制面（建议二选一）：

1. --control-port 暴露本地 HTTP/JSON-RPC 控制接口（审批、mcp reload/list、status）
2. --control-stdin 接收 JSON 命令帧（避免依赖 dare> 文本命令）

这样外部系统可以在任务执行中做审批与热重载。

Phase 3（P2）

统一命令语义（interactive vs headless）

• interactive: 保留当前体验
• headless: 禁止 input()，仅结构化 I/O

---

备注

• DARE 的 A2A server（examples/05-dare-coding-agent-enhanced/a2a_serve.py）已经是很好的外部接入路径。
• 本 issue 的目标是：如果团队希望 “example CLI 本身”也达到 Claude Code/Codex 那种集成友好度，需要补齐哪些最小能力。

[zts212653]

补充澄清（避免误解）：

这条 issue 关注的是 DARE example CLI 作为外部可编排 CLI 的接口形态，不是在说 Cat Café 侧缺能力。

Cat Café 现在的状态是：

• 三猫 MCP 已统一编排（capabilities.json → 生成 .mcp.json / .codex/config.toml / .gemini/settings.json）
• callback 指令是 fallback（MCP 不可用时才注入），不是主路径

所以这里的 gap 结论是：

• 若要“像 Claude Code/Codex CLI 一样被外部宿主稳定编排”，DARE example CLI 仍建议补齐结构化 I/O + 控制面
• 这与 Cat Café 是否支持统一 MCP 无冲突

[zts212653]

基于最新 main（acc2ea96）我再做了一轮全量复核。下面这版专门回应“隐藏要求”：

• 无头模式（headless）
• 运行中动态注入 MCP
• Skills + MCP 的可编排协议面
• 外部宿主对 CLI 输出流的稳定解析（类似 Claude Code / Codex）

也补一句澄清：我们 Cat Café 侧现在是三猫统一 MCP 编排，callback 注入是 fallback，不是主链路。

---

1) DARE 现状：底层能力“有”，但 example CLI 的“宿主友好协议层”不足

A. 输出流（machine-readable）

现状证据

• examples/06-dare-coding-agent-mcp/cli.py:148-253：CLIDisplay + show_event() 将事件转为 [INFO]/[OK]/[ERR] 人类文案。
• examples/06-dare-coding-agent-mcp/cli.py:889-894：参数里没有 --json/--ndjson/--output-format。

结论

• 事件在 CLI 层被“展示化”，外部宿主难以稳定消费生命周期（plan/tool/approval/mcp）细粒度状态。

B. 控制面（运行中可编排）

现状证据

• examples/06-dare-coding-agent-mcp/cli.py:991：主循环 input("dare> ")。
• examples/06-dare-coding-agent-mcp/cli.py:38-46：命令类型只含 approvals/mcp/...，无 skills 控制命令。
• examples/06-dare-coding-agent-mcp/cli.py:538-573：审批通过 DirectClientChannel + TransportEnvelope 进程内调用。

结论

• 现在可“人类交互控制”，但不是“外部宿主可持续接管”的 control plane。
• --script 是批处理，不是双向实时控制协议。

C. 动态 MCP（能力本身存在）

现状证据

• examples/06-dare-coding-agent-mcp/cli.py:488-523：支持 /mcp list|inspect|reload|unload。
• dare_framework/agent/dare_agent.py:287-309：reload_mcp/unload_mcp/inspect_mcp_tools。
• dare_framework/mcp/manager.py / dare_framework/mcp/tool_provider.py：有运行时 reload 基础设施。

结论

• 动态 MCP 底层已经具备，问题是它目前主要暴露在交互命令层，不是稳定的外部控制协议。

D. Skills（能力本身存在，但 CLI 暴露不足）

现状证据

• dare_framework/agent/builder.py:271-355：with_skill_tool/with_sys_skill/skill_store/SkillsActionHandler 已接入。
• dare_framework/skill/_internal/action_handler.py:18-39：已有 skills:list action。
• dare_framework/transport/interaction/resource_action.py:22-25：mcp:* 与 skills:list 均有 canonical action id。
• 但 examples/06.../cli.py:38-46 未提供 /skills ... 命令入口。

结论

• Skills 在 framework 层可用；example CLI 还没把它做成可编排的宿主接口能力。

E. A2A（结构化协议已有）

现状证据

• dare_framework/a2a/server/transport.py:24-160：/.well-known/agent.json + JSON-RPC + SSE(tasks/sendSubscribe)。
• dare_framework/a2a/client/client.py:133-170：已有 SSE 客户端消费。

结论

• DARE 已有“结构化外部协议”路径（A2A）。
• 当前 issue 的 gap 主要是 example CLI 作为可编排 CLI 的接口能力，不是框架整体没协议。

---

2) 和 Claude Code / Codex CLI 的关键差距（补充版）

相比常见“可被宿主自动编排”的 CLI，example CLI 还缺三件核心东西：

1. 稳定事件协议：至少 ndjson + schema version + correlation id。
2. 结构化控制通道：运行中可发 approvals/mcp/skills 指令，而不是依赖 dare> 文本命令。
3. 能力发现握手：启动时声明当前支持哪些 action（actions:list 的 CLI 化暴露）。

---

3) 最小可落地路线（不破坏现有交互 UX）

Phase 1（建议 P1）

新增：

• --headless
• --event-format ndjson
• --schema-version v1

行为：

• stdout 只输出 NDJSON 事件帧，不输出 [INFO]/[OK] 文案。
• 每帧包含最小公共字段：ts,event,run_id,session_id,data。

Phase 2（建议 P1）

新增控制通道（二选一或都支持）：

• --control-stdin（JSON 命令帧）
• --control-port（本地 loopback HTTP/JSON-RPC）

首批命令建议：

• approvals.list/poll/grant/deny/revoke
• mcp.list/reload/show-tool/unload
• skills.list
• actions.list（发现能力）

Phase 3（建议 P2）

模式语义分离：

• interactive：保留现有 /xxx 命令体验
• headless：禁止 input()，仅结构化 I/O

---

4) 验收建议（防止“看起来支持，实际不可编排”）

建议加 3 组集成测试：

1. Headless 协议稳定性

• 启动一次任务，断言 NDJSON 事件序列与 schema（含 error path）稳定。

2. 运行中动态 MCP 注入

• 任务执行中发送 mcp.reload(paths=[...])，随后 mcp.list 能看到新工具并可调用。

3. Skills 能力可发现

• actions.list 返回 skills:list，且 skills.list 可结构化返回技能清单。

---

如果你们愿意，我可以下一条直接给一个“v1 事件 schema 草案 + control command 草案”，便于直接开 PR 实施。

[zts212653]

补充一版可直接实现的协议草案（对应上条评论的 Phase 1/2）。

---

Draft A: Headless NDJSON Event Schema v1

目标：让外部宿主“稳定解析 + 可回放 + 可追踪关联”。

1) 顶层 envelope（每行一个 JSON）

{
  "schema_version": "dare.cli.events.v1",
  "ts": "2026-03-02T03:30:00.123Z",
  "run_id": "run_01H...",
  "session_id": "sess_01H...",
  "seq": 42,
  "event": "tool.result",
  "data": {}
}

字段约束建议：

• schema_version：固定字符串，便于未来并行支持 v2
• ts：ISO8601 UTC
• run_id：单次任务执行唯一 ID（一次 execute）
• session_id：会话 ID（跨 run 可复用）
• seq：单 run 单调递增（幂等/重放友好）
• event：事件类型枚举
• data：事件 payload

2) 事件类型（首批最小集）

lifecycle

• session.started
• task.started
• task.completed
• task.failed

plan

• plan.validated
• plan.invalid

model/tool

• model.response
• tool.invoke
• tool.result
• tool.error

approvals

• approval.pending
• approval.resolved

mcp/skills

• mcp.reloaded
• mcp.unloaded
• skills.listed

3) payload 示例

tool.invoke

{
  "event": "tool.invoke",
  "data": {
    "tool": "read_file",
    "capability_id": "read_file",
    "attempt": 1,
    "call_id": "call_abc123",
    "input": {"path": "README.md"}
  }
}

tool.result

{
  "event": "tool.result",
  "data": {
    "tool": "read_file",
    "call_id": "call_abc123",
    "success": true,
    "output": {"content_preview": "# DARE ..."}
  }
}

approval.pending

{
  "event": "approval.pending",
  "data": {
    "request_id": "req_123",
    "action": "run_command",
    "reason": "needs shell execution",
    "scope_default": "once"
  }
}

approval.resolved

{
  "event": "approval.resolved",
  "data": {
    "request_id": "req_123",
    "decision": "grant",
    "rule_id": "rule_456",
    "actor_session_id": "session-B"
  }
}

---

Draft B: Headless Control Command Schema v1

目标：运行中可被宿主控制，不依赖 /approvals ... 这类文本命令。

建议两种入口任选其一：

• --control-stdin：stdin 一行一个 JSON command
• --control-port：本地 JSON-RPC/HTTP

1) 命令 envelope

{
  "schema_version": "dare.cli.control.v1",
  "id": "cmd_001",
  "action": "approvals.grant",
  "params": {
    "request_id": "req_123",
    "scope": "session",
    "session_id": "session-B"
  }
}

2) 响应 envelope

{
  "schema_version": "dare.cli.control.v1",
  "id": "cmd_001",
  "ok": true,
  "result": {
    "granted": true,
    "rule_id": "rule_456"
  },
  "error": null
}

失败示例：

{
  "schema_version": "dare.cli.control.v1",
  "id": "cmd_009",
  "ok": false,
  "result": null,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "scope=session requires session_id"
  }
}

3) action 命名建议（与现有 ResourceAction 对齐）

• actions.list
• approvals.list
• approvals.poll
• approvals.grant
• approvals.deny
• approvals.revoke
• mcp.list
• mcp.reload
• mcp.show_tool
• mcp.unload
• skills.list

这里建议 CLI action 名称可映射到已有 ResourceAction（approvals:* / mcp:* / skills:list），减少重复实现。

---

Draft C: 启动握手（可选但推荐）

headless 启动后先输出一条 session.started，包含能力清单：

{
  "schema_version": "dare.cli.events.v1",
  "event": "session.started",
  "data": {
    "mode": "headless",
    "supports": {
      "event_stream": "ndjson",
      "control": ["stdin"],
      "actions": [
        "actions.list",
        "approvals.list",
        "approvals.poll",
        "approvals.grant",
        "approvals.deny",
        "approvals.revoke",
        "mcp.list",
        "mcp.reload",
        "mcp.show_tool",
        "mcp.unload",
        "skills.list"
      ]
    }
  }
}

这样宿主不需要猜 CLI 支持什么。

---

如果你们认可这版，我建议直接拆 3 个 PR：

1. --headless + --event-format ndjson（先把事件流稳定下来）
2. --control-stdin（先做最小控制面）
3. actions.list + skills.list（能力发现闭环）

这样风险最低、回归范围也最可控。

[bouillipx]

你似乎分析错地方了，实际cli是在client目录下

[zts212653]

基于协作者提醒，我按 /client 真入口（acc2ea9，2026-03-02）重新做了全量复核。结论分两层：

先纠偏：之前有些结论在 /client 上已经过时

client 现在已经具备：

1. 结构化输出模式（不是只有人类文案）

• client/main.py:920 --output human|json
• client/README.md:302-321 明确了 JSON 行输出（log/event/result）

2. 非交互执行路径

• client/main.py:928-953 有 run / script 子命令（可不走 input()）

3. MCP 动态管理能力（运行时 API 已有）

• client/commands/mcp.py:52-83 reload/unload
• dare_framework/agent/dare_agent.py:287-309 reload_mcp/unload_mcp/inspect_mcp_tools
• dare_framework/mcp/manager.py:98-137 reload/unload 生命周期

4. Skills + MCP 的 action 能力存在

• dare_framework/transport/interaction/resource_action.py:22-25 mcp:* + skills:list
• dare_framework/skill/_internal/action_handler.py:12-39 skills:list handler
• client/commands/info.py:20-21 CLI 可调用 skills:list

所以“完全没有 machine-readable / 没有 skills / 没有动态 mcp”这类说法，在 /client 维度不成立。

---

但对“外部宿主稳定编排”仍有真实 gap（这部分依然成立）

这里聚焦隐藏要求：headless、动态注入 MCP、skills+mcp 协议化、输出流可稳定解析。

Gap A: 缺少明确 headless 协议模式

• 现状：有 run/script，但没有显式 --headless 语义边界；chat 仍是 input("dare> ")（client/main.py:875-900）。
• 影响：宿主可“调用”，但无法依赖统一模式约束（例如禁止交互提示、只输出协议帧）。

Gap B: 运行中控制面仍偏“进程内”而非“宿主可接管”

• TransportActionClient 走 DirectClientChannel.ask()（client/runtime/action_client.py:30-65），本质是同进程内通道。
• CLI 没有 --control-stdin / --control-port 等外部控制入口。
• 影响：外部编排平台难以对“正在运行中的任务”做持续控制（审批、mcp reload、skills 查询）。

Gap C: JSON 输出是“展示型结构化”，不是强协议事件流

• JsonRenderer.emit 直接打印 payload（client/render/json.py:12-13）。
• README 的行结构是 log/event/result（client/README.md:319-321），没有 schema_version/run_id/seq/correlation_id 这类宿主级稳定字段。
• 影响：跨版本兼容、回放/幂等、精确关联能力不足。

Gap D: 动态 MCP 能力可用，但“运行中外部注入”路径不完整

• mcp reload/unload 目前是 CLI 命令或进程内调用可达（client/commands/mcp.py），
• 但缺少外部控制通道去 attach 到活跃 run 并下发结构化命令。
• 影响：我们可以“在会话内人工/脚本操作”，但难做平台级实时编排闭环。

---

对 Cat Café 对接可行性的判断（L1 CLI Adapter 视角）

结论：可接入，但不是零成本，且当前属于“可用但不够优雅”的 L1

可行依据：

• DARE client 已有 run/script + --output json，可以作为外部 CLI 被调用。
• 我们 Cat Café 已有通用 NDJSON/CLI 基础设施与事件变换链路（spawnCli + parser + provider transform）。

我们侧仍需补的硬改动：

1. provider 扩展

• 目前 provider 仍是三值约束：
  • packages/shared/src/types/cat.ts:12 (anthropic|openai|google)
  • packages/api/src/index.ts:166-175 仅三分支 service 构造
• 需要新增外部 provider（例如 dare）及对应 DareAgentService。

2. 事件映射层

• 需把 DARE log/event/result 语义映射到 AgentMessage（至少 session_init/text/error/done，可选 tool/approval/mcp）。

3. 控制与安全桥接

• 我们 callback 侧是 invocationId + callbackToken 强校验（packages/api/src/routes/callback-auth.ts:17-47）。
• DARE 当前控制面不是这类外部托管协议，需要 adapter 侧显式桥接/约束。

---

建议的下一步（最小可落地）

1. DARE 侧（优先）

• 增加 --headless（语义硬切换）
• 增加 --control-stdin（最小外部控制面）
• 为 --output json 增补协议 envelope（schema_version/run_id/seq/event/data）

2. Cat Café 侧（并行）

• 实现 DareAgentService（先接 run --output json）
• 扩 provider schema 与注册工厂
• 做 L1 兼容基线测试（成功流、error 流、超时、取消）

如果大家认可，我可以下一条给一个“client 现有 JSON → 建议 envelope v1” 的最小兼容映射表，便于直接拆 PR。

[zts212653]

按铲屎官要求，这条只做 gap 分析，不展开改造方案。

基线说明：

• DARE 代码基线：main@acc2ea9（2026-03-02）
• 入口：/client（非 examples）
• 对照场景：Cat Café 作为宿主编排外部 CLI agent

---

A. DARE /client 侧 gap（面向外部宿主编排）

P1-1: Headless 合约缺口（语义未硬隔离）

事实

• 有 run/script 非交互子命令（client/main.py:928-953）
• 但无显式 --headless 语义开关；chat 仍依赖 input("dare> ")（client/main.py:875-900）

gap

• 宿主无法依赖“强约束模式”保证只走结构化 I/O（尤其在自动化/服务端调度场景）。

P1-2: 运行中控制面缺口（外部不可持续接管）

事实

• CLI 控制调用核心是 DirectClientChannel.ask(...) 的进程内 action/control（client/runtime/action_client.py:30-65）
• CLI 参数层没有 --control-stdin/--control-port 类外部控制入口（client/main.py:909-1004）

gap

• 外部宿主难以在“活跃执行期间”持续下发结构化控制（审批/MCP/skills 查询）。

P1-3: 事件流 envelope 稳定性缺口

事实

• --output json 输出为 log/event/result 三类行（client/README.md:317-321）
• JsonRenderer.emit 是直接打印 payload（client/render/json.py:12-13）

gap

• 缺少宿主级稳定字段（如 schema_version/run_id/seq/correlation）时，跨版本兼容、幂等重放、精确关联会弱。

P2-1: 动态 MCP 已有能力，但“宿主实时注入闭环”不完整

事实

• CLI 已支持 mcp list/inspect/reload/unload（client/commands/mcp.py:35-83）
• runtime API 也有 reload_mcp/unload_mcp/inspect_mcp_tools（dare_framework/agent/dare_agent.py:287-309）

gap

• 当前更多是会话内/进程内可操作；对“外部宿主在运行时接管并可靠注入”的协议闭环还不够强。

---

B. Cat Café 侧接入 DARE 的 gap（对照我们现状）

P1-1: Provider 扩展口仍有硬约束

事实

• CatProvider 仍是三值：anthropic|openai|google（packages/shared/src/types/cat.ts:12）
• API 注册时仅三分支 service 构造（packages/api/src/index.ts:166-175）

gap

• DARE 作为外部 provider 还不能直接挂载。

P1-2: DARE 适配器缺口

事实

• 我们有通用 CLI/NDJSON 基建（spawnCli、parseNDJSON）
• 但没有 DareAgentService，也没有 DARE 事件到 AgentMessage 的 transform。

gap

• 现阶段无法把 DARE /client --output json 直接纳入我们统一消息语义层。

P1-3: 控制/鉴权模型对齐缺口

事实

• 我们 callback 安全模型依赖 invocationId + callbackToken（packages/api/src/routes/callback-auth.ts:17-47）
• DARE 当前 control path 主要是 CLI 进程内 action/control。

gap

• 外部托管场景下，控制指令的“调用方身份 + 权限边界 + 审计关联”模型尚未对齐。

---

结论（仅分析）

• DARE /client 已是 L1 可接入候选（能力层不弱）。
• 但若目标是“像主流可编排 CLI 一样稳定托管”，当前仍有上述 P1 gap。
• Cat Café 侧也有明确前置 gap（provider 扩展 + DareAdapter + 安全模型桥接）。

以上是本轮只做 gap 分析的结果。

[zts212653]

补一条与 PR #145 对齐的剩余 gap（已在 PR review 标为 P1）：

• script --headless 目前没有审批超时的确定性失败路径。
• 现状是 run --headless 走 _execute_task_with_approval_timeout，但 script --headless 仍走 _execute_task_and_report，当遇到 approval_pending 且缺少外部 control plane 时，可能无限等待。

建议把 script --headless 也纳入 timeout + 结构化 task.failed 语义，并补对应 integration test。

这样 issue #135 的“headless 非交互可托管”语义才能在 run/script 两条入口都闭环。