codsh — 面向 DeepSeek 的终端编码 agent

站点 · 展示画廊 · npm · English | 中文

npm version MIT license dsh-plugin topic dshfind Awesome

> npm:[`codsh-cli`](https://www.npmjs.com/package/codsh-cli) · 命令:`codsh` **codsh** 是面向 DeepSeek —— 以及任何 OpenAI 兼容端点 —— 的终端编码 Agent,直接构建在 [dsh](https://github.com/deepseek-ai/deepseek-harness) 之上,绝非 fork。 核心命令 **`/ship`** 可将一句话需求自动转化为已验证的代码,提供贯穿终端与浏览器的即时任务流全景图。 想看看实际能做出什么?[逛逛展示画廊](https://blackman99.github.io/codsh/gallery.zh.html),查看真实截图并试玩作品。所有项目均从**一句话需求**开始,仅经**一轮交互**,**所有问题均采用推荐答案**完成落地。 ## 安装 ```sh npm install -g @deepseek-ai/dsh codsh-cli export DEEPSEEK_API_KEY="your-api-key" codsh ``` 常用命令与参数: - `codsh -p "任务"` — 直接执行非交互式任务 - `codsh --continue` — 继续上一次会话 - `codsh --resume ` — 恢复指定会话 - `codsh update` — 升级启动器与 profile runtime ## `/ship`:一句话到已验证代码 ```sh /ship 让超长 diff 用分页器打开而不是刷屏滚过 ``` `/ship` 自动驱动 7 阶段工程交付流水线: 1. **前检(Pre-flight)** — 检查工作区状态,创建独立的 `ship/` 分支。 2. **Wayfinder** — 明确交付目标与关键约束,提前解决取舍决策。 3. **Grill** — 结构化设计树访谈,每题自带推荐默认答案。 4. **Spec(Gate 1)** — 产出用户故事、公开接缝与明确的 Out of Scope 边界。 5. **Tickets(Gate 2)** — 拆解垂直切片,构建带显式依赖关系的 DAG 任务网。 6. **落地(Landing)** — 在并行的 Git worktree 中执行 TDD 落地,持续集成与验证。 7. **完成(Done)** — 全量验收通过且仓库无新增失败后,合回原分支。 ### 即时任务流全景图 - **终端 Teaser**:状态行常驻显示票据即时读数(`待认领 n · 已认领 n · 已关闭 n`)、并行 worktree 状态与 Web 流程图链接。 - **双环 ASCII 全景浮层(`Ctrl+G`)**:终端内全屏查看任务依赖 DAG 与认领状态,按 `Ctrl+G` 或点击 Teaser 展开/收起。 - **本地 Web 流程图**:本地回环 React Flow 可视化全景(`127.0.0.1:`),完整展示决策背景、问答历史与阶段切片。 ### 自主恢复与抗冲突 - **自动冲突解决**:三方合并冲突(含 lockfile 与重命名冲突)自动由 agent 协调修复,保留双方意图并自动验证重试。 - **安全中断与续跑**:随时按 `Ctrl+C` 安全中断;输入裸 `/ship` 即可继续未完成的任务。 ## 界面 专为纯键盘高效开发打造的终端交互界面: - **自成空间的终端界面**:备用屏幕全屏呈现,输入框钉底,退出后完整还回原始 shell。 - **DeepSeek 蓝主题**:`/theme` 打开主题选择器,方向键实时预览、`Enter` 保存、`Esc` 还原;`/theme <名称>` 直接切换。`auto`(默认)随终端明暗背景在 `deepseek` / `deepseek-light` 之间自动选择;`terminal` 只使用终端自身的 16 色、不绘制背景。选择保存在 `$DSH_HOME/code-cli-ui.json`,`CODSH_THEME=<名称>` 可在单次启动时覆盖。 - **折叠式思考流**:思考过程默认只占单行,实时流式更新(按 `Ctrl+O` 或点击展开/折叠)。 - **子代理视图矩阵**:后台与并行子代理以独立视图运行(按 `Ctrl+H` 查看列表,点击进入,`Esc` 退出)。 - **跟得上进度的待办清单**:Agent 的待办清单钉在状态行上方(`Ctrl+T` 或点击展开全部)。当清单仍有未完成项、Agent 却已连续 20 次工具调用没有更新它,或上下文压缩把清单挤出了上下文时,codsh 会把当前清单重新交给模型,让钉住的条目跟上实际进度。`CODSH_TODO_REMINDER=<次数>` 可在单次启动时调整这个次数,设为 `off` 则关闭提醒。 - **时间线任意穿梭**:通过 `Shift+←/→` 或 `/jump` 快速跳转轮次;支持用 `/rewind` 从任意轮次分叉探索。 - **快捷交互与操作**: - `Shift+Tab`:切换 Plan 模式 - `Ctrl+Q`:Agent 响应时继续打字排队 - 设置与查看类命令(`/theme`、`/model`、`/effort`、`/thinking`、`/ui`、`/permission`、`/plan`、`/status`、`/view`、`/diff`、`/copy`、`/jump` 等)即使 Agent 正在工作也立即生效,从不进入排队;切换模型或思考强度从当前轮的下一步开始生效 - `Ctrl+C`:快速中断当前操作 - `Ctrl+V`:直接从剪贴板粘贴图片 - `/view`、`/diff`、`/copy`:在内置阅读器中查看文件、未提交改动或代码块 ## 第三方端点 在 `code` profile 自己的补丁层 `$DSH_HOME/profiles/code/cordis.patch.yml`(默认 `~/.dsh/profiles/code/cordis.patch.yml`,在所有 bundle 之后生效)中加入 `llm-pi-ai` 条目,即可接入任何 OpenAI 兼容网关: ```yaml - id: llm-pi-ai config: providers: acme-gateway: displayName: Acme Gateway apiKeyEnv: ACME_GATEWAY_API_KEY api: openai-completions baseURL: https://gateway.acme.example/v1 compat: thinkingFormat: deepseek supportsDeveloperRole: false maxTokensField: max_tokens models: - id: acme-large contextWindow: 65536 maxTokens: 4096 ``` 旧版 dsh 留下的 `$DSH_HOME/settings.yaml` 会在下次启动时导入一次,并改名为 `settings.yaml.imported`;之后请改为编辑该 profile 补丁。 切换并设为默认模型: ```sh /model acme-gateway/acme-large ``` 密钥解析优先级:环境变量 → `$DSH_HOME/.credentials.yaml` → `/.env` → `$DSH_HOME/.env`。 ## 它怎么跑 `codsh` 是一个零依赖启动器,它定位本机的 `dsh`,将 [`codsh-bundle`](https://www.npmjs.com/package/codsh-bundle) 注册进 `code` profile,并启动 `dsh --profile code`。 codsh 需要 dsh 0.2.0-rc.2 或更新版本;本机 `dsh` 更旧时,启动器会拒绝启动,并给出安装新版的命令。`code-cli` 智能体预设以 dsh 预设声明的形式随 bundle 发布(`presets/code-cli.patch.yml`)。dsh 0.1.7 起不再从目录读取预设,旧版 codsh 留在 `$DSH_HOME/.agent-presets/code-cli` 的副本不再生效。 也可以直接使用 dsh 命令运行: ```sh dsh plugin --profile code add codsh-bundle dsh --profile code ``` ## 终端 | 等级 | 终端 | 兼容标准 | |---|---|---| | 一等 | iTerm2、Terminal.app、VS Code 集成终端、tmux、Windows Terminal + WSL | 核心支持,阻塞发版标准 | | 二等 | Ghostty、kitty、Alacritty、Warp | 现代终端特性良好支持,出问题作 bug 处理 | | 尽力支持 | 原生 Windows(pwsh) | 基础交互可用,受限环境暂不支持持久 PTY | 在支持的终端上自动启用 Kitty 键盘协议、焦点感知、OSC 11 颜色查询(据此选择明暗主题)、OSC 12 光标着色(主题强调色,退出时还原)与内联图像。 ## 开发 详见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ```sh pnpm run dev # 启动本地开发界面 pnpm test # 运行单元测试 pnpm run typecheck # TypeScript 类型检查 pnpm run test:e2e # 运行 E2E 测试 ``` ## 交流与反馈 遇到问题、有新想法,或从 Claude Code / Cursor 迁移过来?欢迎提交 [Issue](https://github.com/Blackman99/codsh/issues) 或加入 [Discussions](https://github.com/Blackman99/codsh/discussions)。 ## 许可 [MIT](LICENSE)