# Nextclaw Narp Stdio Runtime Integration

> 当把 Codex、Claude Code、Hermes 或其他外部 agent runtime 通过 NARP stdio 接入 NextClaw，或触达 narp-stdio entry、launcher、agent-side wrapper 和旧 runtime 插件迁移时使用。

- Skill: `peiiii/nextclaw-narp-stdio-runtime-integration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add peiiii/nextclaw-narp-stdio-runtime-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/peiiii/nextclaw-narp-stdio-runtime-integration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: peiiii (https://skillmd.com/u/peiiii)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/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 字段。

## 漂移检查

```bash
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。