kiro2claude: Instructions file for Codex

AGENTS.md

给在此仓库工作的 coding agent(Claude Code / Codex 等)看的规范与地图,只给指针不复述。使用者入口见 README.md;踩坑的来龙去脉见 docs/PITFALLS.md;插件见 docs/PLUGIN-DEVELOPMENT.md;手工探针见 packages/core/test/manual/README.md。

项目一句话

把 kiro-cli(Kiro 后端)包装成 Claude + OpenAI 双协议代理:Claude 全系 + GPT-5.6(Sol / Terra / Luna)走完全相同的上游,两个协议端点都可用。MIT;内置插件 metering(计量)、derived(credit 反演)。Node ≥ 22 / TypeScript / ESM NodeNext / Fastify / pnpm workspace。

Monorepo 边界

packages/plugin-api/            契约包:types + abstract base class,0 runtime deps
packages/core/                  gateway runtime:HTTP 路由、plugin loader、token manager
packages/plugin-metering/       注入 usage.kiro_metering
packages/plugin-derived/        反演 Kiro credit → Anthropic token,注入 usage.kiro_derived
packages/examples/echo-plugin/  公开示范 plugin
packages/core/test/manual/      手工探针(非 CI;部分打真实上游计费),清单见其 README
tools/claude-code/ tools/codex/ 两款真实 CLI 的 Docker harness(非 runtime)
docker/Dockerfile               单一发布镜像(core + 两个内置插件)
.github/workflows/              ci.yml 全 workspace lint+typecheck+test;release.yml 发版

插件都是普通 npm 包:loader 只扫 core 所在 node_modules 第一层(含 @scope/ 下一层、不递归)里带 kiro2claude-plugin keyword 的包,内置与第三方同一机制(契约不加 tier 字段)。

架构地图

packages/core/src/
├── index.ts            入口;config → login → creds → SingleTokenManager → plugin-host → Fastify → 路由 → discoverPlugins
│                       /api/{claude,openai}/v1 = 去泄漏镜像(preHandler 打 stripPluginUsage 标记)
├── token.ts            count_tokens 本地估算 + 远程回退
├── model/config.ts     Config 契约 + loader;env 名 / 默认值 / 校验在 model/schemas/config-schema.ts
├── shared/             横切层(鉴权 / wire-format errors / logger / paths / reqId-ALS)
├── plugin-host/        插件契约实现:hook-bus / usage-finish-event / capability-registry / loader(keyword 扫描 + 拓扑排序)
├── routes/             HTTP 装配层:claude / openai / kiro / health 四组路由
├── kiro/               上游适配层(token-manager / client-profile / provider / retry-executor / parser);
│                       GetUsageLimits 由 index.ts 适配成 'usage-limits' capability
└── claude/             下游兼容层
    ├── converter.ts          Claude→Kiro 请求(system 折叠、当前轮、thinking / effort 字段)
    ├── stream-handler.ts     流式 handler;deferred commit + 空流有界重试
    ├── non-stream-handler.ts 非流式 handler;判空 / 重试镜像
    ├── non-stream-reduce.ts  reduceKiroResponse:claude & openai 非流式共用
    ├── stream.ts             SSE 状态机;buildClaudeUsagePayload / buildKiroUsageFinishEvent / isMeteringLost 唯一定义点
    ├── empty-capture.ts      空流类型 + 诊断抓包
    ├── tool-call-text.ts     泄漏工具调用的检测 / 救援 / 剥除;头注释 = 全部红线
    ├── stream/legacy-thinking-decoder.ts  legacy `<thinking>` 文法唯一定义点
    ├── tool-use-sequence.ts  tool_use 序列 + `parseCompletedToolInput`(「绝不回退 {}」实施点)
    └── reasoning-envelope.ts Claude 签名 / GPT 推理的往返信封

openai/                 OpenAI 兼容层:语义核心复用 claude,只做协议翻译
├── freeform-tool.ts        `type:"custom"` 工具替身编解码的单一真相源
├── stream-transport.ts / non-stream-transport.ts  chat + responses 共用脚手架
└── responses/          Responses API:converter(input items / additional_tools / namespace 展开)、response-stream、
                        response-nonstream、handlers、types