# aicode

**Repository Path**: yanxxit/aicode

## Basic Information

- **Project Name**: aicode
- **Description**: 一个简单的ai 编程工具
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-05
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# aicode

一个轻量的命令行 AI 编程工具，默认使用 **DeepSeek**，兼容任意 OpenAI 协议模型。

> 第一阶段（MVP）：仅打通 "配置模型 → 终端对话 → AI 编程辅助" 的最小闭环。完整需求见 [docs/PRD.md](./docs/PRD.md)。

## 快速开始

```bash
bun install

# 配置 DeepSeek apiKey（写入 ~/.aicoderc.json）
bun run src/index.ts config set providers.deepseek.apiKey sk-xxxxxx

# 或使用环境变量
export AICODE_API_KEY=sk-xxxxxx

bun run src/index.ts ask "用 Node 写一个流式读取大文件的例子"
bun run src/index.ts chat
bun run src/index.ts code src/index.ts "总结这段代码"

# 也可以全局链接命令（直接 aicode <cmd>）
bun link
```

> Bun 原生执行 `.ts`，开发与使用都直接跑源码，无需转译。

## 打包为单文件可执行（可选）

发布给非 Bun 用户时，可生成嵌入运行时的单文件二进制：

```bash
bun run build      # 产出 dist/aicode（约 60MB，无需安装 Bun 即可运行）
./dist/aicode ask "你好"
```

## 命令一览

| 分类 | 命令/入口 | 说明 |
| --- | --- | --- |
| 默认入口 | `aicode` | 默认进入交互式输入框，输入自然语言或 `/` 命令 |
| 常用启动参数 | `--provider`、`--model`、`--no-stream`、`--resume`、`--plan`、`--execute` | 覆盖模型/provider、恢复会话、指定启动模式 |
| CLI 核心命令 | `aicode ask`、`aicode chat`、`aicode code` | 一次性提问、多轮 REPL、带文件上下文编程 |
| CLI 扩展命令 | `aicode verify`、`aicode skills`、`aicode init`、`aicode agents`、`aicode status` | 验证闭环、Skill、Harness 初始化、Agent 与运行态 |
| CLI 命名空间 | `aicode skill show/run`、`aicode agent show/use/current`、`aicode harness sprints/show`、`aicode config list/get/set`、`aicode config shell list/add/remove/disable/enable/reset`、`aicode connect feishu`、`aicode feishu init/status/doctor` | Agentic、Harness、配置、桥接与飞书相关能力 |

更完整的命令口径见 [docs/PRD.md](./docs/PRD.md) 和 [ai-command-semantics.md](./.harness/context/ai-command-semantics.md)。

当前命令文案的代码事实源：

- CLI 描述以 [cli-commands.ts](./src/commands/registry/cli-commands.ts) 为准，由 [index.ts](./src/index.ts) 读取并注册
- CLI 公共 option 描述以 [cli-options.ts](./src/commands/registry/cli-options.ts) 为准，由 [index.ts](./src/index.ts) 读取并注册
- 固定 REPL slash 命令以 [slash-commands.ts](./src/commands/registry/slash-commands.ts) 为准，由 [slash-meta.ts](./src/commands/slash-meta.ts) 组装运行时注册表
- 帮助文案与派生集合分别由 [command-help.ts](./src/commands/registry/command-help.ts) 和 [command-selectors.ts](./src/commands/registry/command-selectors.ts) 生成
- 后续若新增或调整命令，先更新上述 registry，再同步 `README`、`PRD` 与 `.harness/context` 文档，避免口径漂移

### 交互模式斜杠命令

输入框内以 `/` 开头触发：

| 命令 | 说明 |
| --- | --- |
| `/help`、`/?` | 列出全部斜杠命令 |
| `/mode [plan\|execute]` | 查看或切换计划/执行模式 |
| `/spec <sprint-id> [说明]` | 生成或更新 Harness Sprint 的 `spec.md` |
| `/plan <sprint-id> [说明]` | 生成或更新 Harness Sprint 的 `tasks.md` |
| `/approve [id]` | 优先处理普通审批项；若存在遗留 pending write，则兼容直接执行 |
| `/deny <id>` | 拒绝指定审批项 |
| `/execute` | 兼容别名，等价于 `/mode execute` |
| `/exit`、`/quit` | 退出 |
| `/clear` | 清空对话历史 |
| `/sessions` | 列出历史会话 |
| `/resume <编号\|id>` | 恢复指定历史会话 |
| `/rename [name]` | 重命名当前会话 |
| `/compact [说明]` | 压缩当前会话历史，并保留最近窗口 |
| `/auto-verify [on\|off]` | 查看或切换自动验证策略 |
| `/config ...` | 管理 shell 交互规则配置，支持 list/add/disable/enable/reset |
| `/system <text>` | 设置/更新 system 提示 |
| `/model <name>` | 切换模型，并同步当前项目运行态 |
| `/provider <name>` | 切换 provider，并同步当前项目运行态 |
| `/file <path>` | 把文件内容注入为上下文 |
| `/read <path>` | 直接读取并展示文件内容 |
| `/verify [targets]` | 执行验证闭环，支持 `typecheck`、`test`、`build`、`performance` |
| `/tasks` | 查看当前会话的 todos / subtasks 运行态 |
| `/jobs [flags]` | 查看当前会话的后台任务摘要 |
| `/job <id> [--logs]` | 查看单个后台任务详情 |
| `/cancel-job <id>` | 取消指定后台任务 |
| `/status` | 查看当前模式、pending write、tasks、jobs 与最近工具事件 |
| `/save <path>` | 把上一次 AI 回复保存到文件（自动创建父目录） |
| `/write <path>` | 直接把上一条 AI 回复写入目标文件 |
| `/apply` | 直接把上一条 AI 回复中的多文件 `file path=...` 代码块批量写入 |
| `/pending` | 查看当前待写队列 |
| `/confirm [序号列表]` | 执行仍留在待写队列中的失败或遗留写入，可只重试部分文件 |
| `/drop <序号列表>` | 从当前待写队列中移除指定文件 |
| `/cancel` | 取消当前遗留待写项；若无 pending，则回滚最近一次写入 |
| `/stream`、`/no-stream` | 开/关流式输出 |

说明：

- `/save` 仍是“立即保存原始回复”
- `/write`、`/apply` 现在默认直接执行写入；若出现失败项或保留项，再通过 `/pending`、`/confirm`、`/drop` 继续处理
- `/confirm` 主要用于重试当前遗留待写项；可用 `/confirm 1,3-4` 只重试部分文件
- 若队列里有不想继续落盘的文件，可用 `/drop 2` 或 `/drop 1,3-4` 直接移除
- `/cancel` 在存在 pending 队列时会取消遗留项；若当前无 pending，则会回滚最近一次成功写入
- 当前待写队列会随会话一起保存；通过 `--resume <id>` 或 `/resume <编号|id>` 恢复会话后，可继续使用 `/pending`、`/confirm`、`/drop`
- `/sessions` 现在会直接标出哪些历史会话还挂着待写队列，并显示待写文件数量
- 当当前会话仍有 pending 队列时，执行 `/clear`、`/resume`、`/exit` 会先输出未落盘风险提示，再继续执行原命令
- `/config` 为 REPL 内的简化配置入口，例如 `/config add fzf`、`/config list --json --section effective-custom`

### 交互模式 shell 命令

行首输入 `!` 直接执行 shell 命令，不进入 AI 对话历史：

```
aicode › !ls -la
aicode › !git status
aicode › !node examples/foo.js
```

非零退出码会显示 `[aicode] (exit N)`，但不会退出 REPL。

默认情况下，`vim`、`less`、`watch`、`mysql`、`node`、`python`、`go` 等已在内置交互命令表中，会自动切到真实终端交互模式；像 `node script.js`、`python app.py`、`go test ./...` 这类普通执行仍走 capture 模式，把 `stdout/stderr` 原样回写到结果区。

如需自定义交互命令表，可直接修改 `~/.aicoderc.json`，或通过 `config set` 写入 JSON：

```bash
# 追加自定义交互命令
bun run src/index.ts config set shell.interactiveRuleAdditions '[{"id":"terminal-fzf","kind":"command","command":"fzf"}]'

# 禁用默认的 vim 交互规则
bun run src/index.ts config set shell.interactiveRuleRemovals '["editor-vim"]'

# 整体覆盖基础规则表（不推荐，除非你明确知道要替换整套默认值）
bun run src/index.ts config set shell.interactiveRules '[{"id":"terminal-fzf","kind":"command","command":"fzf"}]'
```

说明：

- `shell.interactiveRules`：基础规则表，默认即为内置整套交互命令
- `shell.interactiveRuleAdditions`：按 `id` 追加或覆盖自定义规则
- `shell.interactiveRuleRemovals`：按 `id` 禁用默认规则
- `config set` 现在支持 JSON 字面量；普通字符串写法保持不变

更便捷的 CLI 入口：

```bash
# 查看当前生效规则
bun run src/index.ts config shell list

# 以 JSON 输出规则，便于脚本消费
bun run src/index.ts config shell list --json

# 只看某一段，例如只取当前生效的自定义规则
bun run src/index.ts config shell list --json --section effective-custom

# 追加一条普通交互命令
bun run src/index.ts config shell add terminal-fzf fzf

# 追加一条语言 REPL 规则
bun run src/index.ts config shell add node-repl-custom node --language-repl --deny-flags run,test,-e,-p

# 移除一条规则（默认规则会写入 removals，自定义规则会直接删除）
bun run src/index.ts config shell remove editor-vim

# 与 remove 等价的语义化别名，更强调“禁用默认规则”
bun run src/index.ts config shell disable editor-vim

# 重新启用一条默认规则
bun run src/index.ts config shell enable editor-vim

# 重置为默认规则集
bun run src/index.ts config shell reset
```

`config shell list` 默认按“默认规则 / 已禁用默认规则 / 自定义追加规则 / 当前生效规则”分组展示；加上 `--json` 时输出结构化 JSON。若只关心某一段，可再配合 `--section summary|defaults|removed-defaults|custom-additions|effective-custom|effective` 使用。

### 交互模式 @ 文件引用

输入 `@<查询词>` 模糊搜索仓库内文件：

- 命中 1 个 → 自动选中，并把文件内容注入对话上下文
- 命中多个 → 弹出菜单，**↑/↓ 移动，Enter 确认，ESC 取消**
- 命中 0 个 → 提示无结果，本轮提问不发送

```
aicode › 帮我重构 @chat 里的 /save 实现
选择文件 (匹配 "chat"  ↑↓ 移动  Enter 确认  ESC 取消):
> src/commands/chat.ts
  .harness/context/sprints/sprint_02_harness/tasks.md
```

一行内可同时引用多个 `@xxx`，逐个选择；自动跳过 `.git` `node_modules` `dist` 等目录。

## 配置优先级

CLI 参数 > 环境变量（`AICODE_*` / `DEEPSEEK_API_KEY` / `OPENAI_API_KEY`）> `~/.aicoderc.json` > 默认值。

## 开发模式

- 运行时：Bun ≥ 1.1（同时充当解释器与打包器，无 tsc/webpack）
- Native ESM + TypeScript，源文件即产物