1 line
18 KiB
JSON
1 line
18 KiB
JSON
{"repo": "ccjjllt/my-coding-agent", "files": {"README.md": {"4865df1eb4d5c9c56ccad41d789b26fd69cd7c52": {"t": 1785595221.7059422, "n": 17305, "h": "02cfead2dcc0f7d3", "c": "<p align=\"center\">\n <img src=\"assets/mascots/chovy-idle.gif\" width=\"160\" alt=\"Chovy Code\"/>\n</p>\n\n<h1 align=\"center\">Chovy Code</h1>\n\n<p align=\"center\">\n <strong>English</strong> ·\n <a href=\"README.zh-CN.md\">简体中文</a>\n</p>\n\n<p align=\"center\">\n A pure-JavaScript, terminal-first coding agent: multi-provider LLMs, tool\n orchestration, fine-grained permissions, persistent memory, sub-agents, and\n a React/Ink TUI.\n</p>\n\n<p align=\"center\">\n <a href=\"#screenshots\">Screenshots</a> -\n <a href=\"#requirements\">Requirements</a> -\n <a href=\"#quick-start\">Quick Start</a> -\n <a href=\"#configuration\">Configuration</a> -\n <a href=\"#features\">Features</a> -\n <a href=\"#provider-matrix\">Providers</a> -\n <a href=\"#cli-reference\">CLI</a> -\n <a href=\"#troubleshooting\">FAQ</a> -\n <a href=\"#contributing\">Contributing</a>\n</p>\n\n---\n\n## Screenshots\n\n<p align=\"center\">\n <img src=\"photo/tui_1.png\" width=\"800\" alt=\"Chovy Code TUI - Chat View\"/>\n</p>\n\n<p align=\"center\">\n <img src=\"photo/tui_2.png\" width=\"800\" alt=\"Chovy Code TUI - Tool Execution\"/>\n</p>\n\n---\n\n## Why Chovy Code\n\n- **Single binary, single screen.** One full-screen terminal UI runs every\n workflow: chat, tool calls, sub-agents, memory, multi-agent orchestration.\n- **Pure ESM JavaScript.** No TypeScript compile step. Editor type-checking\n via JSDoc + tsconfig.json only.\n- **Multi-provider out of the box.** Anthropic, MiMo (Anthropic & OpenAI\n compatible), DeepSeek, GLM, Kimi, MiniMax. Auto fail-over within a protocol\n family.\n- **Six-layer permission system.** Tool rules, mode filter, mode coercion,\n auto classifier, user prompt, final render. Plan / Auto / Accept-Edits /\n Bypass / DontAsk modes.\n- **Persistent memory & skills.** SQLite + FTS5 cross-session memory, skill\n registry, hierarchical compaction, auto Dream / Distill consolidation.\n- **Multi-agent built in.** Coordinator dispatches up to 100 worker tasks;\n Arbitrator aggregates with a judge model; tier-based model router.\n\n---\n\n## Requirements\n\n- Node.js 20.x or newer\n- npm 10+\n- macOS / Linux / Windows 10+\n (Windows uses Git Bash, cmd.exe, or PowerShell; override via CHOVY_SHELL)\n- At least one provider API key\n\nOptional:\n\n- Git (used for /diff, commit metadata, formatter discovery)\n- VS Code (the bundled adapter at sdks/vscode/)\n\n---\n\n## Quick Start\n\n### Install from source\n\n```bash\ngit clone https://github.com/<your-org>/chovy-code.git\ncd chovy-code\nnpm install\ncp .env.example .env # then set at least one API key\nnpm run build # bundles dist/tui/index.mjs\nnode bin/tui.mjs\n```\n\n### Install from npm\n\n```bash\nnpm install -g chovy-code\nchovy # full-screen TUI\nchovycode # alias\ncc # short alias\n```\n\n### One-shot run\n\n```bash\nnode bin/tui.mjs --model minimax/MiniMax-M2.7\nnode bin/tui.mjs --mode build --permission acceptEdits ./your/project\nnode bin/tui.mjs --port 27654 # editor bridge mode\n```\n\nIf `dist/tui/index.mjs` is missing, `bin/tui.mjs` rebuilds it via\n`scripts/build-tui.mjs`. Pass `--no-build` to disable that fallback.\n\n---\n\n## Configuration\n\nTwo surfaces: `.env` (secrets + flags) and `chovy.json` (per-project defaults).\n\n### `.env`\n\nEvery provider key is optional; empty providers are skipped. Set one of:\n\n```dotenv\nANTHROPIC_API_KEY=\nDEEPSEEK_API_KEY=\nGLM_API_KEY=\nKIMI_API_KEY=\nMINIMAX_API_KEY=\nMIMO_API_KEY=\n\n# Optional gateway/proxy base URLs (one per provider)\nANTHROPIC_BASE_URL=\nDEEPSEEK_BASE_URL=\nGLM_BASE_URL=\nKIMI_BASE_URL=\nMINIMAX_BASE_URL=\nMIMO_BASE_URL=\n```\n\n`.env` is git-ignored. `.env.example` is the canonical placeholder file and is\nenforced by `npm run verify` (no real secrets allowed).\n\n### `chovy.json`\n\n```json\n{\n \"model\": \"minimax/MiniMax-M2.7\",\n \"default_agent\": \"build\",\n \"permissionMode\": \"default\",\n \"theme\": \"terminal\",\n \"enabled_providers\": null,\n \"disabled_providers\": null\n}\n```\n\nInspect the resolved config without entering the TUI:\n\n```bash\nnode bin/tui.mjs --print-config\nnode bin/tui.mjs --print-providers\n```\n\n### Behavior flags\n\nAll optional. Defaults shown.\n\n| Flag | Default | Effect |\n|---|---|---|\n| `CHOVY_PROXY` | `1` | Engine-level provider fail-over (5xx / 429 / network -> next provider) |\n| `CHOVY_SWARM_CONCURRENCY` | `24` | Coordinator worker concurrency (cap 100) |\n| `CHOVY_ARBITRATE` | `1` | Arbitrator judge-model aggregation |\n| `CHOVY_AUTOROUTE` | `1` | Multi-tier model routing (cheap / standard / strong / verify) |\n| `CHOVY_MEMORY_SEARCH` | `fts` | `fts` SQLite FTS5 or `like` substring scan |\n| `CHOVY_RECALL_LLM` | `1` | LLM-based memory recall selection |\n| `CHOVY_DISABLE_RECALL` | unset | Set `1` to disable per-turn recall |\n| `CHOVY_CHECKPOINT_EVERY` | `5` | Session checkpoint cadence (turns) |\n| `CHOVY_AUTO_DREAM` | `1` | Auto Dream every 8 turns |\n| `CHOVY_AUTO_DISTILL` | `1` | Auto Distill every 16 turns |\n| `DISABLE_AUTO_COMPACT` | unset | Disable auto-compaction |\n| `CHOVY_TUI_DIFF` | `1` | Rich edit diff rendering |\n| `CHOVY_TUI_RICH_RESULTS` | `1` | Structured tool-result rendering |\n| `CHOVY_TUI_MARKDOWN` | `1` | Minimal Markdown rendering |\n| `CHOVY_PATTERN_RECALL` | `1` | Cross-session reusable code-pattern recall |\n| `CHOVY_COORDINATOR_MODE` | unset | Phased orchestrator prompt (Research -> Synthesize -> Implement -> Verify) |\n| `CHOVY_LIVE_TEST` | unset | Run paid live integration tests under `src/__tests__/live/` |\n\n---\n\n## Features\n\n### Engine\n\n- **QueryEngine** (`src/query/QueryEngine.mjs`): 5-layer system prompt\n (override -> coordinator -> agent -> custom -> default), streaming via\n `streamWithProvider()`, tool batching via `runTools()` (read-only parallel,\n write serial), threshold-based auto compaction.\n- **AgentLoop** (`src/services/agent-loop.mjs`): compatibility loop reused by\n sub-agents to share the same provider/parser path.\n- **Protocol Proxy** (`src/proxy/`): bidirectional Anthropic <-> OpenAI\n conversion plus a same-protocol fail-over chain. Cool-down 30s base,\n exponential up to 5 min.\n\n### Tool System\n\nAll tools share the `buildTool()` factory and expose `isReadOnly`,\n`isDestructive`, `checkPermission`. Built-in tools include:\n\n- `Bash`: argv-based shell execution, output truncation, signal-aware abort.\n- `FileRead` / `FileWrite` / `FileEdit`: atomic writes, binary rejection,\n path safety, size caps.\n- `NotebookEdit`: `.ipynb`-only, atomic, size capped.\n- `Glob` / `Grep`: workspace-contained roots, result/length caps, JS fallback\n when `rg`/`ag`/`grep` is missing.\n- `WebFetch` / `WebSearch`: HTTPS-only, private/local host & DNS rejection,\n redirect target validation, response byte caps.\n- `Agent`: sync/background sub-agent launcher.\n- `Compose`: multi-step composition tool.\n- `LSP`, `TodoWrite`, `AskUserQuestion`, `Memory`, `Skill`, `PatternRecall`,\n `Coordinator`, ...\n\nTool registry: `src/tools/index.mjs::getAllTools()`.\n\n### Permission Modes\n\n| Mode | Use case |\n|---|---|\n| `default` | Ask before every destructive action |\n| `acceptEdits` | Auto-approve approved edit flows; still enforces path safety |\n| `plan` | Read-only planning; writes blocked |\n| `auto` | Whitelist + read-only + circuit breaker |\n| `dontAsk` | Never prompt; ambiguous actions deny |\n| `bypassPermissions` | Trusted local workflows only (alias `bypass`, `--dangerously-skip-permissions`) |\n\nSwitch at launch via `--permission acceptEdits` or live in TUI via `/mode`.\n\n### Sub-Agents\n\n`general-purpose`, `Explore`, `Plan`, `verification`, `chovy-code-guide`,\nplus user-defined types under `<cwd>/.chovy/agents/*.md`.\n\n### Multi-Agent Swarm\n\n- `src/swarm/Coordinator.mjs` dispatches up to 100 worker tasks (read-only\n parallel, writes serial).\n- `src/swarm/Arbitrator.mjs` aggregates worker outputs via a judge model into\n `{decision, confidence, synthesis, contributions, dissent}`.\n- `src/services/model-router.mjs` routes by tier: `cheap-explore`,\n `standard`, `strong-reason`, `verify`.\n\n### Memory & Context\n\n- SQLite-backed cross-session memory with FTS5 (`src/memory/MemoryStore.mjs`).\n- Multi-level compaction: `partialCompact`, `microCompact`, `snipCompact`,\n `autoCompact`, `hierarchicalCompact`.\n- Team memory under `<cwd>/.chovy/memory/team/` with multi-layer secret guard.\n- Auto Dream (every 8 turns) and Auto Distill (every 16 turns) consolidate\n into `MEMORY.md` / `SKILL.md`.\n\n### Skills\n\nBundled + project skills (`.chovy/skills/`), conditional activation\n(`paths:` glob), nested discovery, `lazy:` loading.\n\n### Editor Bridge\n\n`node bin/tui.mjs --port 27654` exposes a localhost-only control surface:\n\n```\nGET http://localhost:27654/app\nPOST http://localhost:27654/tui/append-prompt\n```\n\n```json\n{ \"text\": \"In @src/app.mjs#L12-L20\", \"submit\": false }\n```\n\nA first-party VS Code adapter lives in `sdks/vscode/`.\n\n---\n\n## Provider Matrix\n\n| Provider | Protocol | Env var | Sample model id |\n|---|---|---|---|\n| `anthropic` | Anthropic | `ANTHROPIC_API_KEY` | `anthropic/claude-sonnet-4-20250514` |\n| `mimo_anthropic` | Anthropic-compatible | `MIMO_API_KEY` | `mimo_anthropic/mimo-v2.5-pro` |\n| `mimo` | OpenAI-compatible | `MIMO_API_KEY` | `mimo/mimo-v2.5-pro` |\n| `deepseek` | OpenAI-compatible | `DEEPSEEK_API_KEY` | `deepseek/deepseek-chat` |\n| `glm` | OpenAI-compatible | `GLM_API_KEY` | `glm/glm-4.5` |\n| `kimi` | OpenAI-compatible | `KIMI_API_KEY` | `kimi/kimi-k2` |\n| `minimax` | OpenAI-compatible | `MINIMAX_API_KEY` | `minimax/MiniMax-M2.7` |\n\nProvider resolution order (`src/services/providers.mjs::resolveProvider`):\n\n1. Explicit `provider/model` form.\n2. Bare model name -> keyword match (`mimo` defaults to the validated MiMo\n Anthropic-compatible endpoint).\n3. First env-configured provider when nothing is specified.\n\nAdd a self-hosted gateway by setting `<PREFIX>_BASE_URL` (e.g.\n`ANTHROPIC_BASE_URL=https://your-gateway`).\n\nProvider fail-over (default ON): on a transient 5xx / 429 / network error\n**before** the first streamed token, the proxy marks the provider as cooled\ndown and routes to the next same-protocol provider. Set `CHOVY_PROXY=0` to\ndisable.\n\n---\n\n## CLI Reference\n\n```text\nchovy [path] Open project at <path> (default: cwd)\n -m, --model <id> provider/model selector\n --mode <build|plan|...> work mode\n --permission <mode> permission mode\n --port <num> editor bridge port\n --no-build skip auto rebuild of dist/tui\n --print-providers list configured providers and exit\n --print-config print resolved config and exit\n --help show full help\n --dangerously-skip-permissions alias for bypassPermissions\n```\n\nInstalled bins: `chovy`, `chovycode`, `cc`.\n\n## Slash Commands (in TUI)\n\n| Command | Effect |\n|---|---|\n| `/help` | Built-in command reference |\n| `/mode` | Switch work mode |\n| `/permission` | Switch permission mode |\n| `/model` | Switch model |\n| `/agents` | List/select sub-agents |\n| `/memory` / `/memory write <text>` | Show or append memory |\n| `/goal [set <text>\\|clear]` | Show or set the current goal |\n| `/distill` | Mine repeated workflows |\n| `/diff` | Workspace diff via argv-safe `git` |\n| `/clear` | Clear the transcript window |\n| `/exit` | Quit |\n\n---\n\n## Verification & Release Gate\n\n```bash\nnpm run verify\n```\n\nThe local release gate (single command) chains:\n\n1. UTF-8 validation for `.mjs` / `.js` / `.json` / `.md` under `bin/`,\n `src/`, `scripts/`, `docs/`.\n2. Pure-ESM check (no `require(` in `.mjs`).\n3. `package.json` metadata (description, license, keywords, `engines.node`,\n branded bins).\n4. `.env.example` placeholder enforcement.\n5. `node --check` syntax for `bin/tui.mjs` and release scripts.\n6. `node --test src/**/*.test.mjs` (full regression suite).\n7. `npm audit --audit-level=moderate`.\n8. Offline runtime smoke + provider stream smoke + install-from-tarball smoke.\n9. `npm pack --dry-run --json` package-content validation.\n\nRun targeted smokes directly:\n\n```bash\nnpm test # full Node test suite\nnpm run smoke:runtime # offline runtime smoke\nnpm run smoke:providers # offline provider stream smoke\nCHOVY_LIVE_PROVIDER_SMOKE=1 npm run smoke:providers # opt-in live smoke\nnpm run smoke:providers:matrix # provider matrix\nnode scripts/provider-smoke.mjs --matrix --strict # release-grade matrix\n```\n\nThe default smoke path is offline and deterministic. Live and matrix modes\nare opt-in because they consume real provider credits.\n\n---\n\n## Repository Layout\n\n```text\n.\n├── bin/tui.mjs Single product entry point\n├── dist/tui/index.mjs esbuild bundle of the React/Ink TUI (built artifact)\n├── scripts/ build / verify / smoke / install scripts\n├── sdks/vscode/ First-party VS Code adapter\n├── src/\n│ ├── agents/ Built-in + user sub-agent runtime\n│ ├── compact/ Multi-level compaction\n│ ├── coordinator/ Orchestrator mode prompt\n│ ├── ide/ Editor bridge (--port)\n│ ├── memory/ SQLite + FTS5 memory, team memory, secret guard\n│ ├── modes/ Permission & work modes\n│ ├── permissions/ Six-layer permission engine\n│ ├── proxy/ Protocol translation + provider fail-over\n│ ├── query/ QueryEngine + shared stream parser\n│ ├── services/ Providers, llmClient, model-router, repl, tool orchestration\n│ ├── skills/ Skill registry, conditional activation, lazy loading\n│ ├── swarm/ Coordinator + Arbitrator\n│ ├── tools/ All built-in tools + getAllTools() registry\n│ └── tui/ React/Ink terminal UI (production path)\n├── docs/user/ Public-facing docs\n├── assets/mascots/ UI mascots\n├── photo/ TUI screenshots\n├── README.md / AGENTS.md / LICENSE\n└── package.json / chovy.json / tsconfig.json\n```\n\n## Troubleshooting\n\n- **`No API key configured`**: set at least one `*_API_KEY` in `.env`, or\n pass `--model <provider/model>` matching a configured provider.\n- **`Chovy TUI requires an interactive TTY.`**: stdin was piped or you are\n inside a non-TTY runner. Use `--print-providers` / `--print-config` for\n headless inspection.\n- **`dist/tui/index.mjs missing`**: run `npm run build` once, or remove\n `--no-build`.\n- **Windows EBUSY / sqlite locks**: close any other Chovy instance pointing at\n the same `<cwd>/.chovy/memory/`. SQLite uses WAL; `*.db-wal` and `*.db-shm`\n are normal sidecars.\n- **Provider keeps returning 5xx**: `CHOVY_PROXY=1` (default) fails over\n before the first token. After-stream errors are not retried automatically;\n lower-tier provider routes are picked by `CHOVY_AUTOROUTE=1`.\n- **`rg` / `grep` not found**: Grep falls back to a bounded JS scan. Install\n ripgrep for best speed.\n- **Mojibake in TUI**: set the terminal to UTF-8 (`chcp 65001` on Windows).\n All sources are UTF-8 and validated by `npm run verify`.\n- **Sub-agent stuck**: cancel from the TUI or send SIGINT; SpawnManager\n propagates abort and cleans up child processes.\n\n---\n\n## Security & Privacy\n\n- `.env` is git-ignored and excluded from `npm pack` by `scripts/verify.mjs`.\n Never commit real keys.\n- The team-memory writer (`src/memory/teamMemory.mjs`) runs every payload\n through `secretGuard.mjs` (env-assignment, `sk-`/`AKIA`/`ghp_` prefixes,\n private-key blocks, high-entropy tokens).\n- WebFetch / WebSearch reject local/private hosts and follow strict redirect\n target validation.\n- `bypassPermissions` and `--dangerously-skip-permissions` skip user prompts\n but **still** enforce structural path safety. Use only on trusted local\n trees.\n- Bash, FileWrite, FileEdit, NotebookEdit, formatters, Git, MCP, Hooks,\n ProactiveAgent, SSH, Voice, Daemon, Clipboard - all use argv-only\n execution; no shell string interpolation.\n\nReport vulnerabilities privately via GitHub Security Advisories on this repo.\nDo not open public issues for security reports.\n\n---\n\n## Contributing\n\n1. Fork & create a feature branch (`feat/...` or `chore/...`).\n2. Match local style: ASCII by default, Chinese comments allowed near\n existing Chinese comments.\n3. All new source files are `.mjs` ESM. No `require`. No new TypeScript\n files.\n4. Add `*.test.mjs` next to the changed module; run\n `node --test src/path/to/file.test.mjs`.\n5. Before opening a PR, run **`npm run verify`** locally - it must pass.\n6. Update `AGENTS.md` if you change the architecture surface; update\n `docs/user/` if you change user-visible behavior.\n\nPR template (recommended):\n\n```text\n### Summary\n### Scope of change\n### Tests added/updated\n### `npm run verify` result\n### Risks & rollback\n```\n\n---\n\n## Roadmap\n\n- [ ] Stable v1.0.0 release after the open-source cleanup pass.\n- [ ] First-class MCP HTTP/SSE remote transport.\n- [ ] Pluggable provider registry + community providers.\n- [ ] Standalone VSIX bundle for the VS Code adapter.\n- [ ] Optional web UI sharing the engine.\n\n---\n\n## License\n\n[MIT](LICENSE) (c) Chovy Code contributors.\n\nThe mascot art under `assets/mascots/` is (c) Chovy Code and licensed for use\nonly as part of this project's UI.\n\n---\n\n## Acknowledgements\n\nBuilt on top of (and grateful to): Anthropic SDK, OpenAI SDK, Ink, React,\nesbuild, better-sqlite3, glob, commander, zod.\n"}}}} |