coomi-agent 0.1.0__tar.gz

coomi_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Septemc and Flowby
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

coomi_agent-0.1.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: coomi-agent
+Version: 0.1.0
+Summary: 一款纯净的自主 Agent 系统。
+License: MIT
+Project-URL: Homepage, https://github.com/Septemc/Coomi
+Project-URL: Repository, https://github.com/Septemc/Coomi
+Project-URL: Issues, https://github.com/Septemc/Coomi/issues
+Keywords: ai,agent,cli,tui,coding-assistant
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.6.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: textual>=1.0.0
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.104.0; extra == "anthropic"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.7.0; extra == "dev"
+Dynamic: license-file
+
+# Coomi Agent
+
+一个比较纯净的 AI Agent项目。基于CLI的自主 Agent，能读取文件、编辑代码、执行命令、管理任务。
+
+![1780235212332](image/README/1780235212332.png)
+
+## 特性
+
+- **纯净 Agent 设计** — 以开发学习为目标，流程透明，模块边界清晰，便于观察、复盘和二次改造。
+- **核心能力完整** — 覆盖文件操作、搜索、Shell、网页、任务、子 Agent 、 Plan 模式和Loop模式等基础工具链。
+- **可切换的 LLM Provider** — 支持 DeepSeek、OpenAI、Anthropic 和兼容 OpenAI API 的通用服务。
+- **上下文与记忆机制** — 提供上下文压缩、记忆管理、语义召回和工具结果缓存等基础工程能力。
+- **流式终端界面** — 基于 Textual 的 TUI，支持流式输出、工具调用提示和状态信息展示。
+
+## 快速开始
+
+### 环境要求
+
+- Python >= 3.9
+
+### 安装
+
+#### 从 PyPI 安装（推荐）
+
+```bash
+pip install coomi-agent
+```
+
+#### 从源码安装
+
+```bash
+git clone https://github.com/Septemc/Coomi.git
+cd Coomi
+pip install -e .
+```
+
+### Python 环境说明
+
+> **注意**：如果你的系统有多个 Python 环境，`pip install -e .` 会安装到当前 shell 激活的 Python 环境中。
+
+**推荐安装位置**：默认 Python 环境对应的库目录，也就是当前 Python 解释器的 `site-packages`。
+
+| 环境类型    | 常见安装位置                          |
+| ----------- | ------------------------------------- |
+| 系统 Python | `Python 安装目录\Lib\site-packages` |
+| Conda 环境  | `环境目录\Lib\site-packages`        |
+| 虚拟环境    | `项目目录\.venv\Lib\site-packages`  |
+
+**验证当前环境**：
+
+```bash
+# 查看 Python 路径
+which python
+# 或 Windows:
+where python
+
+# 查看 pip 目标路径
+python -m pip show coomi-agent | grep Location
+```
+
+**推荐安装方式**：
+
+先激活你希望使用的默认 Python 环境，再执行：
+
+```bash
+python -m pip install -e .
+```
+
+### 更新
+
+#### 从 PyPI 更新（推荐）
+
+```bash
+pip install --upgrade coomi-agent
+```
+
+#### 从源码更新
+
+```bash
+cd Coomi
+git pull origin main
+pip install -e .
+```
+
+**注意**：从源码安装（`pip install -e .`）时，代码会指向你的本地目录，每次 `git pull` 后无需重新安装。只有当 `pyproject.toml` 中的依赖发生变化时才需要重新执行 `pip install -e .`。
+
+### 首次运行
+
+```bash
+coomi
+```
+
+首次运行时，Coomi 会自动引导你配置 LLM Provider。配置优先级：
+
+1. **环境变量** — 自动检测 `DEEPSEEK_API_KEY`、`OPENAI_API_KEY`、`ANTHROPIC_API_KEY`
+2. **.env 文件** — 项目根目录的 `.env` 文件，用于开发学习使用
+3. **交互式配置** — 终端交互引导
+
+### 配置文件
+
+所有模型配置存储在 `~/.coomi/config/providers.json`：
+
+```json
+{
+  "version": 1,
+  "active": "default",
+  "providers": {
+    "default": {
+      "type": "deepseek",
+      "display": "DeepSeek V4",
+      "api_key": "sk-xxx",
+      "base_url": "https://api.deepseek.com",
+      "model": "deepseek-v4-pro",
+      "fast_model": "deepseek-v4-flash"
+    }
+  }
+}
+```
+
+支持的 Provider 类型：`deepseek`、`openai`、`anthropic`、`generic`（任意兼容 OpenAI API 的服务）。
+
+### 运行方式
+
+```bash
+# CLI 命令（推荐）
+coomi
+
+# 模块运行
+python -m coomi
+```
+
+## 内置命令
+
+| 命令                        | 说明                                            |
+| --------------------------- | ----------------------------------------------- |
+| `/model`                  | 列出所有可用模型                                |
+| `/model <id>`             | 切换到指定 Provider                             |
+| `/context`                | 显示当前上下文窗口大小                          |
+| `/context 256k`           | 设置上下文窗口（如 `128k`、`512k`、`1m`） |
+| `/memory list`            | 列出所有记忆                                    |
+| `/memory add <内容>`      | 添加新记忆                                      |
+| `/memory search <关键词>` | 搜索记忆                                        |
+| `/memory delete <名称>`   | 删除记忆                                        |
+| `/clear`                  | 清除当前会话                                    |
+| `exit` / `quit`         | 退出                                            |
+
+## 架构
+
+```
+coomi/                          # 主包
+├── __init__.py                 # 版本信息
+├── __main__.py                 # python -m coomi 入口
+├── cli.py                      # CLI 入口（coomi 命令）
+├── setup.py                    # 首次配置引导
+├── types.py                    # Message, Session, ToolCall, LLMResponse
+├── engine/
+│   ├── loop.py                 # AgentLoop — 感知-决策-执行循环
+│   └── session.py              # SessionManager，System Prompt 构建器
+├── services/
+│   ├── llm/                    # Provider 层（抽象基类 + 4 种实现）
+│   │   ├── provider.py         # LLMProvider 抽象基类
+│   │   ├── generic.py          # GenericOpenAIProvider（配置驱动）
+│   │   ├── deepseek.py         # DeepSeekProvider（thinking mode）
+│   │   ├── openai.py           # OpenAIProvider
+│   │   ├── anthropic.py        # AnthropicProvider（可选依赖）
+│   │   ├── factory.py          # Provider 工厂 + Flash 模型降级
+│   │   └── config.py           # ConfigManager（~/.coomi/config/providers.json）
+│   ├── context/
+│   │   ├── compressor.py       # 三层压缩
+│   │   └── cache.py            # 工具结果磁盘缓存
+│   └── memory/
+│       ├── manager.py          # 三层记忆存储
+│       ├── extractor.py        # 对话自动提取
+│       └── recall.py           # 语义记忆召回
+├── tools/                      # 15+ 内置工具
+│   ├── file_ops/               # Read, Write, Edit
+│   ├── search/                 # Glob, Grep
+│   ├── shell/                  # Bash, PowerShell
+│   ├── web/                    # WebFetch, WebSearch
+│   ├── task/                   # TodoWrite
+│   ├── agent/                  # 子 Agent 委托
+│   ├── user/                   # AskUserQuestion
+│   └── workspace/              # Plan 模式（进入/退出）
+└── ui/                         # Textual TUI 界面
+    ├── textual_app.py          # 主应用
+    ├── status_line.py          # 状态栏（模型 + Token 用量）
+    ├── tool_formatter.py       # 工具调用详情格式化
+    ├── screens/                # 屏幕
+    └── widgets/                # 组件
+```
+
+## 上下文压缩
+
+三层压缩，当前估算 Token 数超过上下文窗口 90% 时触发：
+
+1. **Microcompact（微清理）** — 将超出保留数量（6 条）的旧工具结果内容替换为 `[cleared]` 标记。零 API 开销。
+2. **消息裁剪** — 保留第一条消息 + 最近 8 条消息。零 API 开销。
+3. **LLM 摘要** — 生成 9 段结构化摘要（核心需求、关键概念、文件与代码、错误与修复、问题解决、用户消息、待办任务、当前工作、建议下一步）。使用当前模型。
+
+## 记忆系统
+
+三层存储，优先级逐级递减：
+
+1. `.coomi/memory/` — 项目本地（最高优先级）
+2. `~/.coomi/projects/{hash}/memory/` — 项目全局
+3. `~/.coomi/memory/` — 全局（所有项目共享）
+
+记忆类型：`user`（用户偏好）、`feedback`（反馈纠正）、`project`（项目上下文）、`reference`（外部引用）。
+
+MemoryExtractor 自动分析对话并保存相关记忆。MemoryRecall 执行语义选择，将相关记忆注入 System Prompt。
+
+## 项目参考来源
+
+本项目在工程复现和实现思路上参考了以下项目（或源码实现，或界面交互体验）：
+
+- Claude Code
+- Codex
+- OpenCode
+
+参考重点主要是 Agent 主循环、工具调用编排、上下文管理和终端交互方式，不代表与原项目具有相同实现或功能范围。
+
+## License
+
+MIT，详见 [LICENSE](LICENSE)

coomi_agent-0.1.0/README.md

@@ -0,0 +1,224 @@
+# Coomi Agent
+
+一个比较纯净的 AI Agent项目。基于CLI的自主 Agent，能读取文件、编辑代码、执行命令、管理任务。
+
+![1780235212332](image/README/1780235212332.png)
+
+## 特性
+
+- **纯净 Agent 设计** — 以开发学习为目标，流程透明，模块边界清晰，便于观察、复盘和二次改造。
+- **核心能力完整** — 覆盖文件操作、搜索、Shell、网页、任务、子 Agent 、 Plan 模式和Loop模式等基础工具链。
+- **可切换的 LLM Provider** — 支持 DeepSeek、OpenAI、Anthropic 和兼容 OpenAI API 的通用服务。
+- **上下文与记忆机制** — 提供上下文压缩、记忆管理、语义召回和工具结果缓存等基础工程能力。
+- **流式终端界面** — 基于 Textual 的 TUI，支持流式输出、工具调用提示和状态信息展示。
+
+## 快速开始
+
+### 环境要求
+
+- Python >= 3.9
+
+### 安装
+
+#### 从 PyPI 安装（推荐）
+
+```bash
+pip install coomi-agent
+```
+
+#### 从源码安装
+
+```bash
+git clone https://github.com/Septemc/Coomi.git
+cd Coomi
+pip install -e .
+```
+
+### Python 环境说明
+
+> **注意**：如果你的系统有多个 Python 环境，`pip install -e .` 会安装到当前 shell 激活的 Python 环境中。
+
+**推荐安装位置**：默认 Python 环境对应的库目录，也就是当前 Python 解释器的 `site-packages`。
+
+| 环境类型    | 常见安装位置                          |
+| ----------- | ------------------------------------- |
+| 系统 Python | `Python 安装目录\Lib\site-packages` |
+| Conda 环境  | `环境目录\Lib\site-packages`        |
+| 虚拟环境    | `项目目录\.venv\Lib\site-packages`  |
+
+**验证当前环境**：
+
+```bash
+# 查看 Python 路径
+which python
+# 或 Windows:
+where python
+
+# 查看 pip 目标路径
+python -m pip show coomi-agent | grep Location
+```
+
+**推荐安装方式**：
+
+先激活你希望使用的默认 Python 环境，再执行：
+
+```bash
+python -m pip install -e .
+```
+
+### 更新
+
+#### 从 PyPI 更新（推荐）
+
+```bash
+pip install --upgrade coomi-agent
+```
+
+#### 从源码更新
+
+```bash
+cd Coomi
+git pull origin main
+pip install -e .
+```
+
+**注意**：从源码安装（`pip install -e .`）时，代码会指向你的本地目录，每次 `git pull` 后无需重新安装。只有当 `pyproject.toml` 中的依赖发生变化时才需要重新执行 `pip install -e .`。
+
+### 首次运行
+
+```bash
+coomi
+```
+
+首次运行时，Coomi 会自动引导你配置 LLM Provider。配置优先级：
+
+1. **环境变量** — 自动检测 `DEEPSEEK_API_KEY`、`OPENAI_API_KEY`、`ANTHROPIC_API_KEY`
+2. **.env 文件** — 项目根目录的 `.env` 文件，用于开发学习使用
+3. **交互式配置** — 终端交互引导
+
+### 配置文件
+
+所有模型配置存储在 `~/.coomi/config/providers.json`：
+
+```json
+{
+  "version": 1,
+  "active": "default",
+  "providers": {
+    "default": {
+      "type": "deepseek",
+      "display": "DeepSeek V4",
+      "api_key": "sk-xxx",
+      "base_url": "https://api.deepseek.com",
+      "model": "deepseek-v4-pro",
+      "fast_model": "deepseek-v4-flash"
+    }
+  }
+}
+```
+
+支持的 Provider 类型：`deepseek`、`openai`、`anthropic`、`generic`（任意兼容 OpenAI API 的服务）。
+
+### 运行方式
+
+```bash
+# CLI 命令（推荐）
+coomi
+
+# 模块运行
+python -m coomi
+```
+
+## 内置命令
+
+| 命令                        | 说明                                            |
+| --------------------------- | ----------------------------------------------- |
+| `/model`                  | 列出所有可用模型                                |
+| `/model <id>`             | 切换到指定 Provider                             |
+| `/context`                | 显示当前上下文窗口大小                          |
+| `/context 256k`           | 设置上下文窗口（如 `128k`、`512k`、`1m`） |
+| `/memory list`            | 列出所有记忆                                    |
+| `/memory add <内容>`      | 添加新记忆                                      |
+| `/memory search <关键词>` | 搜索记忆                                        |
+| `/memory delete <名称>`   | 删除记忆                                        |
+| `/clear`                  | 清除当前会话                                    |
+| `exit` / `quit`         | 退出                                            |
+
+## 架构
+
+```
+coomi/                          # 主包
+├── __init__.py                 # 版本信息
+├── __main__.py                 # python -m coomi 入口
+├── cli.py                      # CLI 入口（coomi 命令）
+├── setup.py                    # 首次配置引导
+├── types.py                    # Message, Session, ToolCall, LLMResponse
+├── engine/
+│   ├── loop.py                 # AgentLoop — 感知-决策-执行循环
+│   └── session.py              # SessionManager，System Prompt 构建器
+├── services/
+│   ├── llm/                    # Provider 层（抽象基类 + 4 种实现）
+│   │   ├── provider.py         # LLMProvider 抽象基类
+│   │   ├── generic.py          # GenericOpenAIProvider（配置驱动）
+│   │   ├── deepseek.py         # DeepSeekProvider（thinking mode）
+│   │   ├── openai.py           # OpenAIProvider
+│   │   ├── anthropic.py        # AnthropicProvider（可选依赖）
+│   │   ├── factory.py          # Provider 工厂 + Flash 模型降级
+│   │   └── config.py           # ConfigManager（~/.coomi/config/providers.json）
+│   ├── context/
+│   │   ├── compressor.py       # 三层压缩
+│   │   └── cache.py            # 工具结果磁盘缓存
+│   └── memory/
+│       ├── manager.py          # 三层记忆存储
+│       ├── extractor.py        # 对话自动提取
+│       └── recall.py           # 语义记忆召回
+├── tools/                      # 15+ 内置工具
+│   ├── file_ops/               # Read, Write, Edit
+│   ├── search/                 # Glob, Grep
+│   ├── shell/                  # Bash, PowerShell
+│   ├── web/                    # WebFetch, WebSearch
+│   ├── task/                   # TodoWrite
+│   ├── agent/                  # 子 Agent 委托
+│   ├── user/                   # AskUserQuestion
+│   └── workspace/              # Plan 模式（进入/退出）
+└── ui/                         # Textual TUI 界面
+    ├── textual_app.py          # 主应用
+    ├── status_line.py          # 状态栏（模型 + Token 用量）
+    ├── tool_formatter.py       # 工具调用详情格式化
+    ├── screens/                # 屏幕
+    └── widgets/                # 组件
+```
+
+## 上下文压缩
+
+三层压缩，当前估算 Token 数超过上下文窗口 90% 时触发：
+
+1. **Microcompact（微清理）** — 将超出保留数量（6 条）的旧工具结果内容替换为 `[cleared]` 标记。零 API 开销。
+2. **消息裁剪** — 保留第一条消息 + 最近 8 条消息。零 API 开销。
+3. **LLM 摘要** — 生成 9 段结构化摘要（核心需求、关键概念、文件与代码、错误与修复、问题解决、用户消息、待办任务、当前工作、建议下一步）。使用当前模型。
+
+## 记忆系统
+
+三层存储，优先级逐级递减：
+
+1. `.coomi/memory/` — 项目本地（最高优先级）
+2. `~/.coomi/projects/{hash}/memory/` — 项目全局
+3. `~/.coomi/memory/` — 全局（所有项目共享）
+
+记忆类型：`user`（用户偏好）、`feedback`（反馈纠正）、`project`（项目上下文）、`reference`（外部引用）。
+
+MemoryExtractor 自动分析对话并保存相关记忆。MemoryRecall 执行语义选择，将相关记忆注入 System Prompt。
+
+## 项目参考来源
+
+本项目在工程复现和实现思路上参考了以下项目（或源码实现，或界面交互体验）：
+
+- Claude Code
+- Codex
+- OpenCode
+
+参考重点主要是 Agent 主循环、工具调用编排、上下文管理和终端交互方式，不代表与原项目具有相同实现或功能范围。
+
+## License
+
+MIT，详见 [LICENSE](LICENSE)

coomi_agent-0.1.0/coomi/__init__.py

@@ -0,0 +1,8 @@
+"""Coomi Agent — 受 Claude Code 启发的 AI 编程助手"""
+
+__version__ = "0.1.0"
+__author__ = "Septemc"
+
+from .types import Message, ToolCall, LLMResponse, Session
+
+__all__ = ["Message", "ToolCall", "LLMResponse", "Session"]

coomi_agent-0.1.0/coomi/__main__.py

@@ -0,0 +1,5 @@
+"""允许 python -m coomi 运行"""
+from .cli import main
+
+if __name__ == "__main__":
+    main()

coomi_agent-0.1.0/coomi/async_utils.py

@@ -0,0 +1,10 @@
+"""异步工具"""
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+
+async def run_in_thread(func, *args: Any, **kwargs: Any) -> Any:
+    """在线程池中执行同步函数，返回结果"""
+    return await asyncio.to_thread(func, *args, **kwargs)

coomi_agent-0.1.0/coomi/cli.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+"""Coomi Agent CLI 入口"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+def main():
+    """主入口函数"""
+    # 检查是否首次运行（无配置文件）
+    config_dir = Path.home() / ".coomi" / "config"
+    config_path = config_dir / "providers.json"
+
+    if not config_path.exists():
+        # 首次运行：引导配置
+        from .first_run import run_first_time_setup
+        if not run_first_time_setup():
+            sys.exit(0)
+
+    # 启动 TUI
+    from .ui.textual_app import CoomiApp
+    app = CoomiApp()
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

coomi_agent-0.1.0/coomi/engine/__init__.py

@@ -0,0 +1,37 @@
+# 引擎层 - Agent大脑
+from ..types import Message, ToolCall, LLMResponse, Session, TokenUsage, Spec, LoopSession, Checkpoint, LoopStatus, StepResult
+from .session import SessionManager, add_user_message, add_assistant_message, add_tool_result, update_token_usage, build_system_prompt
+from .loop import AgentLoop
+from .spec_parser import parse_spec_file
+from .checkpoint import create_loop_dir, save_state, save_checkpoint, append_issue, load_state
+from .retry_policy import RetryPolicy, RetryAction
+from .loop_runner import LoopRunner
+
+__all__ = [
+    "Message",
+    "ToolCall",
+    "LLMResponse",
+    "Session",
+    "TokenUsage",
+    "Spec",
+    "LoopSession",
+    "Checkpoint",
+    "LoopStatus",
+    "StepResult",
+    "SessionManager",
+    "add_user_message",
+    "add_assistant_message",
+    "add_tool_result",
+    "update_token_usage",
+    "build_system_prompt",
+    "AgentLoop",
+    "parse_spec_file",
+    "create_loop_dir",
+    "save_state",
+    "save_checkpoint",
+    "append_issue",
+    "load_state",
+    "RetryPolicy",
+    "RetryAction",
+    "LoopRunner",
+]