catyans/cathead-coding

Cathead Coding
一个能力出众的编程智能体，爪子柔软，工具锋利。

Cathead Coding 是一个开源、支持 Gemini 的编程智能体 CLI，由 DeepSeek Harness 驱动。它让产品体验保持小巧友好，同时将困难的部分——智能体执行、工具、会话、沙箱和模型路由——委托给 DSH。

[!IMPORTANT]
Cathead Coding 是一个早期的开发者预览版。请在受版本控制的工作区中运行它，并审查生成的更改。

它为何会发出呼噜声

- 交互式多轮终端聊天
- 智能体工作时可排队输入，并在下一个工具边界进行引导
- 按 Esc 取消可停止当前回合而不离开会话
- 用于脚本和 CI 的非交互式 run 模式
- 通过 /auto 实现有边界的自主目标（16 轮或 30 分钟）
- 通过 DSH 的提供商中立 llm-pi-ai 适配器使用 Gemini
- 工作区写入的文件和 shell 沙箱
- 使用 --resume 和感知工作区的 --continue 实现持久化本地会话
- 实时流式输出、工具活动、审批和用户提问
- 终端原生 Markdown，支持标题、代码块、列表、任务列表、表格和链接
- 计划模式，带渲染审查、Todo 进度、token/上下文压力和自动压缩
- 模型切换、会话搜索/重命名/分叉、Git worktree 状态和后台任务视图
- 进程内和分叉的子智能体，带实时“猫咪团队”状态
- 工作区指令和本地 Skill 发现

环境要求

- Node.js 22.19 或更新版本
- pnpm 10 或更新版本
- 一个 Gemini API 密钥
- 当前沙箱化 Bash 运行时需要 macOS 或 Linux

让猫进来

git clone https://github.com/catyans/cathead-coding.git
cd cathead-coding
pnpm install
pnpm build
npm link

export GEMINI_API_KEY="your-key"
node dist/cli.js doctor
cathead --cwd /path/to/project

从一个任务开始：

cathead "fix the failing tests"

不使用交互式 UI 运行：

cathead run --cwd /path/to/project "review the current diff"

流式输出机器可读事件：

cathead --cwd /path/to/project run --output jsonl "run the tests"

恢复某个工作区的最新会话，或恢复指定会话：

cathead --cwd /path/to/project --continue
cathead --cwd /path/to/project --resume session-abc123
GOOGLE_GENERATIVE_AI_API_KEY 可作为 GEMINI_API_KEY 的别名使用。密钥由私有 DSH 运行时子进程继承，绝不会写入 Cordis 配置。

配置

| 环境变量               | 默认值                | 用途                                 |
| ---------------------- | --------------------- | ------------------------------------ |
| GEMINI_API_KEY       | —                     | Gemini 身份验证                      |
| CATHEAD_PROVIDER     | google              | DSH 提供商路由                       |
| CATHEAD_MODEL        | gemini-2.5-flash    | 模型 ID                              |
| CATHEAD_SESSION_ROOT | ~/.cathead/sessions | 持久化 DSH 会话                      |
| CATHEAD_QUERY_PATH   | ~/.cathead/*.sqlite | 派生的本地会话搜索索引               |
| CATHEAD_DSH_CONFIG   | 捆绑配置              | 备用 Cordis 运行时组合               |

默认运行时在 config/cordis.yml 中声明。这一显式组合是 Cathead Coding 与 DSH 之间的产品边界；部署可以替换它，而无需分叉任一项目。

交互控制

| 输入                             | 行为                                                        |
| -------------------------------- | ----------------------------------------------------------- |
| 输入                             | 行为                                                        |
| -------------------------------- | ----------------------------------------------------------- |
| Enter                          | 立即发送，或在 Cathead 忙碌时排队作为下一轮                 |
| Shift-Enter / Ctrl-Enter     | 在编辑器中插入换行                                          |
| Alt-Enter                      | 在下一个工具边界处进行引导                                  |
| ↑ / ↓                        | 浏览提示历史                                                |
| PageUp / PageDown            | 在最新 Markdown 回答中按块翻页                              |
| Esc                            | 取消当前轮次；交互会话保持打开                              |
| Ctrl-C                         | 忙碌时取消；空闲时按两次退出                                |
| Ctrl-D                         | 输入为空时退出                                              |
| /plan [task] / /plan off     | 进入规划模式（可选带任务），或退出该模式                    |
| /compact                       | 压缩符合条件的对话历史                                      |
| /auto               | 启动一个上限为 16 轮或 30 分钟的目标                        |
| /continue [guidance]           | 再添加一个有界目标批次                                      |
| /pause / /cancel             | 暂停自动目标或取消当前轮次                                  |
| /queue / /steer        | 查看排队的工作或注入引导                                    |
| /sessions [query]              | 列出或搜索持久会话                                          |
| /rename  / /fork      | 重命名或分叉当前会话                                        |
| /models / /model      | 列出模型，或切换提供商/模型及推理强度                       |
| /context / /diff / /agents | 检查 token 用量、Git 状态或子代理团队                       |
| /clear / /exit               | 清空视图或关闭 Cathead                                      |

助手回复和计划审查以终端原生 Markdown 渲染。图像不会尝试绘制 sixel 或 Kitty 图形；Cathead 会显示其替代文本和路径/URL，从而保持输出的可移植性。

交互模式有意要求真实的 TTY。对于管道、任务运行器、日志和 CI，请使用 cathead run；Cathead 绝不会将交互式调用静默转换为一次性请求。

架构

Terminal UI / run command
│
▼
Cathead session controller
│ private NDJSON bridge over stdio
▼
DSH Host ApiProxy + Cordis composition
│
├── Gemini provider
├── agent spine
├── workspace sandbox
├── filesystem + Bash tools
├── plans, goals, Todo, compaction, and token meter
├── background jobs + subagent providers
├── approval/question providers
└── durable sessions + projection cache

控制器拥有一个长期存活的 DSH 会话，并将其事件流折叠为持久转录状态、临时流式状态、工具活动、队列状态、目标和交互。模型回合进入空闲状态不会卸载 UI 或关闭运行时。有关生命周期和净室设计边界，请参阅 docs/architecture.md。

安全模型

内置策略将文件系统和 shell 写入限制在选定的工作区内。更广泛访问的请求会以显式交互式批准的形式呈现。无头运行会拒绝交互式请求并以状态码 2 退出。自动目标是有界的，且必须显式续期。会话默认存储在 ~/.cathead 下；API 密钥由私有运行时进程继承，不会持久化到项目配置中。

开发

pnpm install
pnpm dev
pnpm check

在提交拉取请求之前，请参阅 CONTRIBUTING.md。安全报告遵循 SECURITY.md。

路线图

- 全屏差异查看器和更丰富的逐工具卡片
- 键盘驱动的会话/模型选择器浮层
- 在超大代码块和子代理转录窗格内进行细粒度滚动
- Windows PowerShell 组合

许可证

MIT