claw-code 源码分析:Agent 产品化最后一公里——Harness 工程里哪些模块决定「能卖」还是「只能 demo」?
涉及源码:
rust/crates/runtime、api、tools、claw-cli、server、plugins、lsp、mcp*,对照PARITY.md与rust/README.md的版本叙事。
1. 先约定「能卖」与「demo」在本文中的含义
这不是法律或销售定义,而是 工程就绪度 的粗分:
| 维度 | Demo 足够 | 可对外售卖 / 企业落地 通常还需要 |
|---|---|---|
| 智能体闭环 | 能在一台机器上跑通「用户话 → 模型 → 工具 → 回写」 | 稳定多轮、失败可恢复、可观测、可限流 |
| 数据与租户 | 单用户、本机文件 | 鉴权、多租户隔离、审计与留存策略 |
| 扩展与策略 | 内置工具 + 固定配置 | 插件/钩子/技能管线可运营,策略可审计 |
| 集成面 | CLI / 单次 API | 常驻服务、IDE/LSP、远程会话等可依赖的契约 |
| 合规与沙箱 | 信任开发者本人 | 权限默认值、沙箱、数据出境可控 |
下面按 模块 映射到 claw-code 现状。
注意:PARITY.md 成文较早,其中 hooks 在 runtime 未执行 等判断与 当前 conversation.rs 已接入 HookRunner 的实现 不一致;读缺口文档时应对照源码 HEAD。
2. 「心脏」:决定有没有资格叫 Agent 产品
2.1 ConversationRuntime(runtime/conversation.rs)
负责 API 请求组装 → 流式事件 → assistant 消息 → 权限 →(PreHook)→ 工具执行 →(PostHook)→ tool_result 回注 的闭环。没有这一层,只剩「聊天 UI」或「单次补全」。
- 产品化价值:统一的错误轨(
RuntimeError/ToolError)、可测的迭代上限、TurnSummary产出。 - 仍为 demo 风险点:
max_iterations、模型与工具失败策略、重试与退避若未系统化,线上仍脆弱(需运维层补)。
2.2 api + Provider 凭证(OAuth / claw login)
没有稳定 鉴权与流式协议解析,工具再多也无法对接真实模型服务。claw-cli 的 login / token 持久化属于 可分发产品 的基础能力。
2.3 tools(mvp_tool_specs + execute_tool)
工具注册表与执行入口决定 场景覆盖(读仓库、改文件、Web、子 Agent 等)。PARITY.md 指出相对 TS 大量工具族仍缺(MCP 资源枚举、LSP、AskUser、定时任务等)——直接影响 能否替代原版工作流,而非「能不能跑」。
3. 「信任与边界」:从玩具到可交付
3.1 permissions(PermissionPolicy / PermissionOutcome)
把 工具调用 从「全能 bash」收窄到模式(read-only / workspace-write / danger-full-access)及每工具要求。企业场景下这是硬门槛;缺失则只能做个人 hackathon。
3.2 hooks(runtime/hooks.rs + 配置合并)
Pre/Post 工具钩子支持 策略外置、审计、DLP 类扩展(见 result/24.md)。
当前源码 已在 ConversationRuntime 中调用 HookRunner,与旧版 PARITY.md「仅解析不执行」描述 已不同;是否满足某客户 SOP 仍取决于脚本治理与失败语义,属 集成层 问题。
3.3 sandbox(runtime/sandbox.rs)
SandboxConfig / SandboxStatus 等表达 「期望隔离」与「实际是否支持」;若长期 supported: false 或默认关闭,对 不可信代码/多用户 场景仍偏 demo。
3.4 plugins(crates/plugins)
插件模型与 HookRunner::from_registry 等提供 扩展面。PARITY.md 仍写 Rust 无插件子系统,与 存在 plugins crate 的现状不符;更准确的表述是:与 TS 的安装/市场/生命周期相比仍不完整,是否「能卖」取决于你是否承诺「客户可自行装插件」。
4. 「集成与运维」:决定能不能接进客户环境
4.1 claw-cli(交互 REPL、slash commands、session 文件)
本地开发者 可每日使用 的形态:会话落盘、resume、/compact 等命令面——这是 0.1 产品 的主叙事(rust/README.md 版本与平台说明)。
4.2 lsp(LSP 客户端与 prompt enrichment)
决定 能否吃进 IDE 诊断/符号,是 严肃编码助手 与 纯终端 demo 的分水岭之一;深度与稳定性决定商业化话术上限。
4.3 mcp_*(stdio / remote / managed proxy)
MCP 决定 与外部系统(文档、DB、内部 API)的 标准对接;缺省仅内置工具时,产品边界停在「个人本机」。
4.4 server(crates/server)——典型 demo 形态
HTTP 提供 POST /sessions、GET /sessions/{id}/events(SSE)等,但 send_message 仅把用户消息写入 Session 并广播,未调用 ConversationRuntime::run_turn,也未接 Provider:
// 200:220:rust/crates/server/src/lib.rs
async fn send_message(
State(state): State<AppState>,
Path(id): Path<SessionId>,
Json(payload): Json<SendMessageRequest>,
) -> ApiResult<StatusCode> {
let message = ConversationMessage::user_text(payload.message);
let broadcaster = {
let mut sessions = state.sessions.write().await;
let session = sessions
.get_mut(&id)
.ok_or_else(|| not_found(format!("session `{id}` not found")))?;
session.conversation.messages.push(message.clone());
session.events.clone()
};
let _ = broadcaster.send(SessionEvent::Message {
session_id: id,
message,
});
Ok(StatusCode::NO_CONTENT)
}
会话存储为 进程内 HashMap,无持久化、无认证。
结论:server 当前更适合 演示实时通道 / 前端原型,不是与 claw-cli 等价的「可售卖 Agent API」。产品化最后一公里往往要在这里 接上 runtime + 持久化 + AuthN/Z。
5. 「技能与内容」:决定差异化是不是可运营
5.1 prompt + CLAW.md / 工程上下文
系统提示与工程文件 discovery 影响 输出质量与一致性;属于 可卖体验 的核心,但难单独写进合同 SLI,需与 评测与日志 配合。
5.2 skills / commands(Rust)
Slash 与技能发现决定 用户可发现能力;PARITY.md 指 技能无 TS 式 registry/bundled 管线 时,规模化运营(统一分发、版本、审计)仍弱。
6. Python src/:明确的「移植工作台」,非售卖主形态
清单镜像、QueryEnginePort、parity CLI 等服务于 理解、对照与测试(result/26.md),不承担与 Rust 相同的产品 SLA。对外若混淆二者,容易把 demo 工作区 当成 交付运行时。
7. 汇总表:模块 → 更像「能卖」还是「仍 demo」
| 模块 / 面 | 偏向 | 说明 |
|---|---|---|
ConversationRuntime + api + tools + permissions |
能卖内核 | 本地 Agent 闭环与信任边界的主干 |
oauth / login、会话文件路径 |
能卖内核 | 可安装、可重复使用的最低配置 |
mcp_*、lsp |
能卖增强 | 深度集成与外部系统;完成度决定上限 |
hooks、plugins、sandbox |
看集成与默认值 | 有能力 ≠ 已满足合规;TS 级运营面仍可能有缺口 |
server |
当前偏 demo | 无 LLM 闭环、内存会话、无 API 认证 |
compat-harness |
对齐/兼容 | 上游清单抽取;不单独构成产品 |
Python src/ |
非售卖主路径 | 移植与诚实 parity |
8. 一句话
能卖 的 harness 通常要求:runtime 闭环 + 凭证与配置 + 权限/钩子/沙箱叙事可信 + 工具与 MCP/LSP 覆盖真实工作流;仍 demo 的典型信号是:HTTP 面只有消息搬运没有推理环、无持久化与多租户、工具与技能运营链断裂。claw-code 的 Rust 核心已具备前者雏形;server 与 PARITY 所列 TS 级能力差距,正是「最后一公里」在源码上的落点。
更多推荐



所有评论(0)