# klynx

`klynx` 是独立的 PyPI Agent 框架库（不依赖 `kbase` 才能运行）。

## 安装

```bash
pip install klynx
```

开发模式：

```bash
pip install -e libs/klynx
```

可选功能：

1. 浏览器工具：`playwright install chromium`
2. 联网搜索：配置 `TAVILY_API_KEY`
3. TUI 依赖（已在 `klynx` 依赖中声明）：`textual`、`pyte`

## 最小用法

```python
import os
from klynx import create_agent, setup_model

api_key = os.getenv("DEEPSEEK_API_KEY", "")
model = setup_model("deepseek", "deepseek-chat", api_key)

agent = create_agent(
    working_dir=".",
    model=model,
    max_iterations=30,
    memory_dir=".",
    load_project_docs=False,
)

for event in agent.invoke("读取当前目录并给出项目结构概览", thread_id="demo"):
    if event.get("type") == "done":
        print(event)
```

默认创建后的 agent 已经加载最小必要工具集，无需再调用 `agent.add_tools("all")`。

默认 active tool groups 为：

1. `system`
2. `core`

默认可用的主路径能力包括：

1. `execute_command`
2. `read_file`
3. `apply_patch`
4. `write_to_file`
5. `list_directory`
6. `update_task_state`
7. `write_todos`

推荐工作流：

1. `execute_command(rg --files / rg -n)` 搜索
2. `read_file` 定点精读
3. `apply_patch` 最小修改
4. `execute_command` 验证

## 工具加载策略

从当前版本开始，`klynx` 不再推荐默认全量加载工具。

推荐按需加载工具组：

```python
# 默认 create_agent() 后已经有 system + core

# 需要结构化文件辅助工具时
agent.add_tools("group:extended_fs")

# 需要终端 / TUI 交互时
agent.add_tools("group:interactive")

# 需要联网搜索 / 浏览器时
agent.add_tools("group:network_and_extra")
```

仍然兼容显式全量加载：

```python
agent.add_tools("all")
```

但这只建议用于调试或旧示例兼容，不再作为默认推荐用法。

### 可用工具组

1. `group:core`
   - 本地代码任务默认主路径工具
2. `group:extended_fs`
   - `search_in_files`、`preview_file`、`create_directory` 等辅助文件工具
3. `group:interactive`
   - 终端与 TUI 交互工具
4. `group:network_and_extra`
   - `web_search`、浏览器类工具

### 新增交互工具

终端侧新增：

1. `wait_terminal_until`
2. `read_terminal_since_last`
3. `run_and_wait`

TUI 侧新增：

1. `read_tui_diff`
2. `read_tui_region`
3. `find_text_in_tui`
4. `send_keys_and_read`
5. `wait_tui_until`

## 安全与状态后端

`create_agent(...)` 现支持以下参数：

1. `checkpointer`：注入自定义 LangGraph checkpointer（默认 `MemorySaver`）。
2. `tool_virtual_root`：限制文件工具访问边界（默认 `working_dir`）。
3. `allow_shell_commands`：控制 `execute_command` 是否可用（默认 `True`）。

示例：

```python
from langgraph.checkpoint.memory import MemorySaver

agent = create_agent(
    working_dir=".",
    model=model,
    checkpointer=MemorySaver(),
    tool_virtual_root=".",
    allow_shell_commands=True,
)
```

## Skills 用法

Skill 是一个目录，目录里至少有 `SKILL.md`。

### 1. 内置 skills

内置 skills：`skill-creator`、`skill-installer`。

```python
agent.basic_skills("off")  # 关闭内置 skills
agent.basic_skills("on")   # 重新开启
```

### 2. 安装外部 skills

```python
# 推荐：显式 name/path/description
agent.add_skills("my-skill", r"E:\\skills\\my-skill", "可选描述")

# description 可为空
agent.add_skills("my-skill", r"E:\\skills\\my-skill", "")

# 也支持路径/名称简写
agent.add_skills(r"E:\\skills\\my-skill")
agent.add_skills("my-skill")
```

### 3. 记忆目录自动发现 skills

当设置 `memory_dir` 后，会自动扫描：

```text
<memory_dir>/.klynx/skills/
```

该目录下每个 skill 子文件夹都会被自动注册为可用 skill。

### 4. 运行时引用 skills

1. 模型需要调用 `load_skill(name)` 把 `SKILL.md` 注入上下文。
2. 在 TUI 或 CLI 输入中可用 `$skill-name` 引用，例如：`$skill-creator`。

说明：

1. 默认 prompt 中只保留 skills 的元信息摘要。
2. 只有显式调用 `load_skill(name)` 后，对应 `SKILL.md` 正文才会进入当前 turn 上下文。

## TUI

推荐安装独立 TUI 包后直接运行：

```bash
pip install klynx-cli
klynx
```

源码仓库内的 TUI 入口在 `klynx_cli/`：

```bash
python klynx_cli/tui_app.py
```

当前 `klynx_cli` 的默认策略也已跟随库的工具加载方式调整：

1. 默认使用 agent 自带的最小工具集（`system + core`）
2. 不再无条件调用 `add_tools("all")`
3. 只有在配置中显式声明 `tools_include` 时，才额外扩张工具面

详细说明见：`klynx_cli/README.md` 和 `docs/tui_tutorial.md`。

## Agent 上下文拼装策略

当前默认策略（`libs/klynx/klynx/agent/prompt_builder.py`）：

1. 统一抽取 native + xml 工具事件（native 从 `additional_kwargs.tool_calls`，xml 从 assistant content）。
2. `context_summary` 与 `recent_history` 同时注入，避免摘要后丢失新对话。
3. 历史分层压缩：
   - 早期历史：重压缩（保留关键执行证据）
   - 最近历史：轻压缩（保留更多自然语言语义）
4. 主推理消息拆分为 `SystemMessage + HumanMessage`，工具详细说明保留在 system，task_context 仅注入工具名摘要，降低重复 token。

## 示例

见 `tutorials/examples/`：

- `basic_agent_example.py`
- `plan_act_agent.py`
- `direct_answer_agent_example.py`
- `no_summary_like_agent_example.py`

示例说明见 `tutorials/README.md`。

## 文档导航

- `docs/klynx_tutorial.md`：klynx 库教程
- `docs/tui_tutorial.md`：TUI 使用教程
- `docs/kbase_tutorial.md`：kbase 教程
- `docs/tutorials_examples_guide.md`：示例说明文档

