peiiii / nextclaw-narp-stdio-runtime-integration

NARP Stdio Runtime Integration

架构合同

• core/kernel/service 只识别通用 narp-stdio，不得硬编码具体 runtime/provider id。
• runtime 身份只存在于 agents.runtimes.entries、installer/repair/marketplace metadata、具体 wrapper package 和显式测试配置。
• Codex、Claude Code 等用户入口保持独立 marketplace skill；公共 NARP 协议实现复用，不合并用户入口。
• host-side stdio client 保持通用；provider 差异属于 agent-side wrapper/bridge。
• 旧 SDK runtime package 可作为 library 复用；除非它有阻塞 bug，不因迁移顺手修改。
• 配置使用 type: "narp-stdio"、config.wireDialect: "acp" 和具体 config.command。

实现顺序

1. 冻结不得触达的通用 client、旧 SDK 和核心边界。
2. 复用通用 agent-side wrapper，把 NcpAgentRuntime 暴露为 NARP stdio 子进程。
3. 为具体 runtime 提供薄 wrapper package 与 <runtime>-narp launcher。
4. 通过显式 runtime entry 注册，不在核心注入默认 provider 分支。
5. 真实验收同时证明 entry、launcher 可执行、launcher 指向当前待验构建物和模型真实回复。

实现前核对

• 结构：读取目标 package 的 module structure、tsconfig、现有 role 目录和同类 bridge/mapper 落点；新增路径走目录 preflight。
• 上游协议：用最小直连/mock 确认 stream、provider 参数、thinking/reasoning 字段和错误形状。
• 模型路由：确认用户模型 id 是否带 provider 前缀，以及上游前的剥离/映射位置。
• raw event：改 NCP mapper 前先看 SDK/CLI 是否暴露目标增量，还是把 bridge 增量聚合为 snapshot。
• 构建入口：确认 launcher/bin 指向当前源码构建的 dist，不是旧全局版本；改 bridge/wrapper 后重建相关包。
• 配置安全：只核对 apiBase、wireApi、model 和 enabled，不输出 key、token 或 extra headers。

核对后先判断第一个错误 owner：provider bridge、runtime SDK mapper、agent-side wrapper、host-side stdio client 或服务 SSE；owner 不明确时不修改业务代码。

能力验收

完成当前 runtime 集成 slice 后返回生命周期，由 Validation 阶段选择 NCP Chat 冒烟合同。按本次目标断言：

• 文本：固定 marker、text delta 和最终文本；
• 工具：tool-call start/result 与最终 marker；
• 思考：reasoning start/delta/end 与非空 reasoning text；
• 组合：agent runtime 至少一轮 thinking + tool + final text；
• 流式：增量随上游到达，不能完成后一次吐出；
• 连续性：同一产品 session 稳定映射同一 runtime session。触达绑定/恢复时验证首轮 marker、重启、追问，并核对持久化 runtime id；触达模型切换时再验证切换 provider/model 后上下文和 runtime id 不丢。

结论必须写成 runtime + provider/model + capability，不能用一个 provider 代表 runtime，也不能用文本成功代表工具或思考。

分层缩圈

按 provider 直连 -> bridge -> SDK/CLI raw event -> agent-side wrapper -> host-side stdio -> service SSE 找第一个错误 hop；每轮只验证一个假设。若用户问题发生在 dev URL，必须用进程证据确认真实子进程来自当前仓库，而不是转发到全局包。

真实冒烟默认隔离 NEXTCLAW_HOME 和 launcher bin；必要时隔离 runtime home。修改后重建 dist，长期进程重启或新开 session，输出全部脱敏。

Bridge 与 Reasoning

• 分别确认上游 thinking 参数、provider 原始字段、bridge 目标形状和 SDK/CLI raw event。
• 不可读 reasoning 先在三段流中定位首次空白丢失或改写，不在展示 mapper 统一伪造摘要；内容型 delta reader 不得 .trim() 文本、reasoning 或 tool arguments。
• 修一个同构 bridge 后横向搜索 sibling runtime 的 stream reader、normalizer 和 event mapper。
• MiniMax M2 的 ChatCompletions 可能需 reasoning_split: true；桥到 OpenAI Responses/Codex 时要核对 runtime 实际消费的 reasoning.summary 形状，不能只填另一个 reasoning 字段。

漂移检查

rg -n 'codex|claude|nextclaw-codex|nextclaw-claude' packages/nextclaw-core/src packages/nextclaw-kernel/src packages/nextclaw-service/src

若命中来自新 provider 硬编码、默认 entry 注入、kind 特判或注册绕过，移到配置、installer 或 wrapper owner。