Metadata-Version: 2.4
Name: abyss-cli
Version: 2.0.4
Summary: 终端AI开发助手
Author: Abyss Team
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0.0
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: ddgs>=9.0.0
Requires-Dist: httpx>=0.20.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: tokenizers>=0.15.0
Requires-Dist: jinja2>=3.0.0
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: indexing
Requires-Dist: onnxruntime>=1.17; extra == "indexing"
Requires-Dist: numpy>=1.24; extra == "indexing"

# Abyss CLI

> 终端 AI 开发助手 · 类似 Claude Code，一个命令启动，一切在工具内完成。

![Python](https://img.shields.io/badge/Python-3.9%2B-blue)
![Version](https://img.shields.io/badge/version-2.0.4-green)

Abyss 是一个运行在终端里的 AI 开发助手：启动后通过自然语言驱动文件读写、Shell 执行、网页搜索等内置工具完成开发任务，并内置**长期记忆**、**知识库**、**子代理**、**Skill**、**MCP**、**Hook** 等扩展能力。默认采用复古 CRT 黑客风格 UI（绿色荧光 + 扫描线底纹）。

## ✨ 功能特性

- **对话式开发**：多轮对话驱动工具调用，支持流式输出、思考过程显示（可开关）
- **内置工具**：`file_read` / `file_write` / `file_edit` / `shell_exec` / `web_search` / `web_fetch` / `todo_write`
- **子代理（Subagent）**：并行拆分复杂任务，内置 Token 预算与费用核算
- **长期记忆**：跨会话记忆，BM25 检索 + LLM 重排（`/memory`）
- **知识库**：沉淀与归档经验知识，支持搜索、固定、统计（`/knowledge`）
- **Skill 系统**：可加载方法论（TDD、调试纪律、架构扫描等），自带 Curator 生命周期管理（`/skills`、`/curator`）
- **MCP 支持**：接入外部 MCP Server 与工具（`/mcp`）
- **Hook 机制**：PreToolUse 拦截、PostToolUse 审计，可安装扩展包（如 `security-hooks` 安全加固）
- **上下文管理**：自动/手动上下文压缩（`/compact`）、会话统计（`/stats`）
- **Token 计费面板**：累计/逐轮明细与费用（`/token`），集成 DeepSeek 官方定价
- **Git 集成**：`/git` 归因命令族、`/diff` 查看差异、`/undo` / `/redo` 文件编辑回滚
- **AI 分析命令**：`/bug-hunter`、`/pr-review`、`/security-scan`、`/explain`、`/advisor`
- **Plan Mode**：只读规划模式，写/执行工具被门控（`/plan-mode`）
- **自适应思考预算**：根据上下文动态调节 `reasoning_effort`，省 token
- **自纠错循环**：工具调用失败自动重试修正（SelfCorrectionLoop）
- **安全防护**：路径安全校验、敏感信息过滤、危险命令黑名单、工具安全门卫

## 🚀 安装

要求 Python ≥ 3.9。

```bash
# 从源码安装（推荐开发模式）
pip install -e .

# 或仅安装
pip install .
```

安装完成后即可使用 `abyss` 命令：

```bash
abyss
```

## ⚙️ 配置

首次启动需要配置 API Key（默认使用 DeepSeek）：

```bash
# 启动后在交互界面中设置
/config set api-key sk-xxxx

# 或直接编辑配置文件 ~/.abyss/config.json
```

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `api_key` | 空 | API Key |
| `base_url` | `https://api.deepseek.com` | API 地址 |
| `api_format` | `responses` | LLM 接口格式（Responses / Chat Completions） |
| `model` | `deepseek-v4-pro` | 默认模型 |
| `model_fallbacks` | `["deepseek-v4-flash"]` | 模型自动降级链 |
| `thinking` | `true` | 是否开启思考模式 |
| `reasoning_effort` | `medium` | 思考强度 |
| `ui.theme` | `hacker` | 界面主题（`hacker` / `default`） |
| `ui.show_tps` | `true` | 输出速率（tok/s）展示：实时状态行 + 轮末 STREAM 汇总 + `/token` 速率列 |
| `plan_mode` | `false` | 只读规划模式 |

### 命令行参数

```bash
abyss                    # 启动
abyss -m deepseek-v4-flash   # 指定模型
abyss -r                 # 恢复上次会话
abyss -r 会话名          # 恢复指定会话
abyss --hide-reasoning   # 隐藏思考过程
abyss -v                 # 显示版本
```

## 📖 Slash 命令

| 分类 | 命令 |
| --- | --- |
| 基础 | `/help` `/clear` `/exit` `/session` |
| 会话 | `/retry` `/compact` `/undo` `/redo` `/stats` `/token` `/logs` |
| Git | `/diff` `/git` |
| AI 分析 | `/bug-hunter` `/pr-review` `/security-scan` `/explain` `/advisor` |
| 扩展 | `/skills` `/mcp` `/hooks` `/curator` `/knowledge` |
| 记忆 | `/memory` |
| 方法论 | `/diagnose` `/tdd` `/review` `/audit` `/architecture` `/prototype` `/domain` |
| 配置 | `/model` `/effort` `/thinking` `/show-reasoning` `/plan-mode` `/config` `/version` |

自定义命令：在 `~/.abyss/commands/` 下放置 `.md` 文件即可注册新的 slash 命令。

## 🔌 Hook 扩展包

`security-hooks` 是通过 Hook 机制实现的安全加固包，**不修改核心代码**：

- **PreToolUse**：拦截危险 `shell_exec` 调用、禁止写入敏感目录、防知识库路径遍历
- **PostToolUse**：记录全部工具调用到 `~/.abyss/logs/tool-audit.log`

```bash
# 安装
abyss extension install file://./security-hooks --id security-hooks --type hook

# 卸载
abyss extension remove security-hooks
```

## 🧪 测试

```bash
pip install pytest
pytest tests/
```

## 📂 项目结构

```
src/abyss/
├── main.py            # CLI 主入口
├── agent_loop.py      # 工具执行循环 / 自纠错
├── ansi_menu.py       # ANSI 补全菜单
├── api_client.py      # 原生 httpx LLM 客户端
├── session.py         # 会话管理
├── context_engine.py  # 上下文压缩
├── commands/          # slash 命令实现
├── tools/             # 内置工具
├── subagent/          # 子代理
├── memory/            # 长期记忆（BM25 + 重排）
├── knowledge/         # 知识库
├── skills/            # Skill 加载
├── mcp/               # MCP 管理
├── hooks/             # Hook 运行器
├── security/          # 安全防护
├── ui/                # 主题渲染（hacker CRT）
└── llm/               # LLM 弹性重试
```

## 📄 License

本项目尚未指定开源许可证。上传到 GitHub 前请自行选择（如 MIT / Apache-2.0）并添加 LICENSE 文件。
