integrate-harness

分类: 测试与安全 | 上传者: a5c-ai | 下载: 0 | 版本: v1.0（最新）

将新的代理工具（基于 CLI 的编码代理）适配器添加到代理复用器时使用。涵盖功能审核、适配器支架、会话解析、身份验证检测、挂钩/插件接线、测试和文档。

更新日志: Source: GitHub https://github.com/a5c-ai/agent-mux

目录结构

当前层级: tree/main/.claude/skills/integrate-harness/

📄 SKILL.md 3.3 KB

SKILL.md

---
name: integrate-harness
description: Use when adding a new agent harness (CLI-based coding agent) adapter to agent-mux. Covers capability audit, adapter scaffold, session parsing, auth detection, hooks/plugins wiring, tests, and docs.
---

# integrate-harness

Goal: produce a production-quality `XAdapter extends BaseAgentAdapter` with full test coverage and documentation, matching the level of the existing 11 adapters (claude, codex, cursor, gemini, opencode, openclaw, copilot, hermes, pi, omp, agent-mux-remote).

## Checklist

1. **Capability audit** — read the harness's CLI docs. Fill in every `AgentCapabilities` field. Unknown? Set conservatively (`false`) and note in PR.
2. **Create `packages/adapters/src/<name>-adapter.ts`** extending `BaseAgentAdapter`. Required: `agent`, `displayName`, `cliCommand`, `minVersion`, `hostEnvSignals`, `capabilities`, `models[]`, `defaultModelId`, `configSchema`, `buildSpawnArgs`, `parseEvent`, `detectAuth`, `getAuthGuidance`, `sessionDir`, `parseSessionFile`, `listSessionFiles`, `readConfig`, `writeConfig`.
3. **Session parsing** — if the harness stores JSONL sessions, delegate to `parseJsonlSessionFile`; otherwise write a custom parser and unit-test each event shape.
4. **Hooks** — if the harness supports native hooks, override `writeNativeHook` and mirror into `HookConfigManager`. If not, rely on the base class's virtual hooks.
5. **Plugins** — if it supports MCP servers under `mcpServers` in its config JSON, flip `supportsPlugins: true`, add `pluginFormats: ['mcp-server']`, and delegate to `mcp-plugins.ts` (see cursor/gemini/opencode/openclaw for the pattern).
6. **Register** — add to `packages/adapters/src/index.ts` exports and to the default registry in `packages/core/src/client.ts` (if applicable).
7. **Tests** — in `packages/adapters/tests/<name>-adapter.test.ts`:
   - capability shape
   - `buildSpawnArgs` for a few representative `RunOptions`
   - `parseEvent` for each JSONL type the harness emits
   - `detectAuth` for authenticated + unauthenticated states
   - session file parsing from a real fixture (redacted)
   - If plugins: add the adapter to `mcp-plugins-parity.test.ts`.
8. **CLI audit test** — ensure `packages/cli/tests/commands-audit.test.ts` passes (it exercises every adapter via the built CLI).
9. **File-size limit** — each source file must stay under 400 effective lines (`local/max-file-lines`). Split helpers into sibling modules if you're close.
10. **Docs** — add a row to the README capabilities matrix and a paragraph in `docs/02-agents/<name>.md`.
11. **Changeset** — `npm run changeset`, pick `minor` (new adapter), summarize.

## Verification

```bash
npm run typecheck
npm run lint
npm test
npx vitest run packages/adapters/tests/<name>-adapter.test.ts
```

All existing tests must continue to pass — no regressions in commands-audit.

## Common pitfalls

- Forgetting to add the adapter to the default registry → `commands-audit.test.ts` won't exercise it.
- JSONL parsers that assume a single event per line — some harnesses emit arrays.
- Auth detection that reads env vars synchronously at construction time instead of `detectAuth()` — breaks testability.
- `buildSpawnArgs` returning the string `"undefined"` for missing options — always gate with `if (options.X != null)`.
- Hook writers that overwrite rather than merge — use `appendJsonHook` or `appendYamlHook`.

登录后下载/点赞/收藏 ❤ 8 | ★ 0

integrate-harness

目录结构

SKILL.md

举报内容

提示