# 项目名称：OpenJerry 个人本地智能体
## 项目背景
参考 Hermes Agent 设计理念，构建一个轻量化、可扩展的本地个人AI智能体 OpenJerry。核心能力依靠 Skill 插件体系做能力扩展，面向本地文件操作、Shell执行、长期记忆管理，优先实现完整CLI交互版本，后续预留Web/App扩展接口。
> 重要参考：Skills 渐进式披露规范严格遵循 https://agentskills.io/home 的设计思想实现。

## 整体功能需求
### 1. LLM模型接入层
1. 完全兼容所有实现 OpenAI Chat Completions API 接口规范的大模型服务，支持本地模型、第三方API中转服务。
2. 配置项支持：API‑KEY、Base‑URL、模型名称、temperature、max_tokens 等通用参数；参数可通过配置文件、CLI入参两种方式设置。
3. 请求异常处理：网络超时、API返回错误码、限流做友好错误提示，CLI输出清晰日志，不直接抛出原始堆栈给终端用户。
4. 支持流式输出与非流式输出两种模式，CLI默认开启流式打印对话内容。

### 2. 智能体内置基础工具集（必实现，内置不可卸载）
所有工具遵循 function‑call 规范，工具入参校验，执行结果结构化返回给大模型。
内置工具清单：
1. `read_file`：读取指定路径文件内容；支持相对路径（根约束在工作目录`./workspace`）；文件不存在返回明确错误信息；限制超大文件读取保护。
2. `write_file`：新建/覆盖写入文件；默认根目录约束`./workspace`；支持创建多级父目录。
3. `edit_file`：增量编辑文件，支持片段替换、行范围修改，避免全量重写；校验修改范围，输出变更摘要。
4. `run_shell`：执行宿主系统Shell命令；⚠️无沙箱，命令直接在宿主环境运行；返回stdout、stderr、退出码；输出过长做截断提示。
5. `memory_read`：读取长期记忆文件 `./OPENJERRY.md`，获取历史记忆片段。
6. `memory_append`：向 `./OPENJERRY.md` 追加新记忆条目；自动做简单时间戳标记，记录关键对话结论、用户偏好、重要事实。
7. `memory_search`：简单关键词检索 `./OPENJERRY.md` 记忆内容，返回匹配片段。
8. `list_dir`：列出工作目录下文件夹、文件列表，辅助智能体探索本地项目文件。

> 安全约定：文件读写默认工作目录为 `./workspace`；工具做路径防护，禁止跳出工作目录访问系统敏感文件；Shell不做沙箱隔离，代码直接宿主执行，启动时CLI打印安全风险警告提示用户。

### 3. Skill 插件系统：严格遵循 Skills 渐进式披露原理（agentskills.io）
1. Skill 存放目录约定：`./skills`，每个Skill独立文件夹，包含skill元数据、描述、工具定义、实现代码。
2. **渐进式披露核心逻辑必须严格实现**
   - 智能体启动时**不会一次性把全部Skill全部注入system prompt**；
   - 初始只向大模型披露少量基础内置工具；
   - 当大模型判断当前任务需要某一项外部Skill能力时，才动态加载、披露对应Skill的function定义给LLM；
   - 任务结束后可回收临时加载的Skill，避免上下文被大量无关工具污染；
   - Skill具备元信息：名称、简介、触发条件、能力描述、依赖参数；支持启用/禁用开关。
3. Skill开发规范：支持Python实现自定义Skill，定义工具schema；支持热加载（可选）；提供最小Skill示例模板，方便用户编写自定义扩展技能。
4. 生命周期：Skill注册 → 未披露状态 → 条件触发动态披露给LLM → 工具调用执行 → 任务完成可卸载回收。

### 4. 长期记忆模块
1. 持久化存储文件固定路径：`./OPENJERRY.md`，markdown格式，人工也可以直接打开编辑记忆内容。
2. 记忆条目格式建议：时间戳 + 事实摘要 + 来源（对话/工具执行结果）。
3. 配套内置工具：memory_read / memory_append / memory_search，供智能体主动读写记忆；
4. 智能体策略：对话过程中自主判断哪些信息需要沉淀长期记忆，不需要每次对话全部把完整记忆塞进prompt；按需检索记忆片段注入上下文。
5. 区分：短期会话上下文内存（本次对话） vs 长期持久记忆（OPENJERRY.md）。

### 5. 目录规范
- 默认工作目录：`./workspace` —— 用户项目文件读写根目录，所有文件工具默认路径约束到此目录
- `./skills`：存放第三方/自定义Skill插件
- `./OPENJERRY.md`：全局长期记忆文件
- `./config.yaml`：配置文件，存放LLM接口配置、技能开关、系统参数
- `./logs`：运行日志目录，记录工具调用历史、LLM请求日志

### 6. 部署运行约束
1. Python >=3.10，使用标准现代Python项目结构，pyproject.toml管理依赖。
2. **第一阶段只完成完整CLI版本**；代码架构层面预留抽象层，后续可以低成本扩展Web端、App后端接口，不要把逻辑和CLI强耦合死。
3. 无沙箱说明：Shell命令、文件修改直接操作宿主机器，启动程序打印醒目安全警告，提示用户不要在不信任Skill下运行。

## 系统架构设计要求
整体分层，模块解耦，便于后续迭代Web/API服务：
1. **Config配置层**：yaml配置 + cli参数合并，统一管理LLM、路径、开关参数
2. **LLM Client层**：封装OpenAI兼容接口，统一流式/非流式调用，异常捕获
3. **Agent Core 智能体核心**：会话管理、system prompt组装、工具调度循环、思考‑行动闭环
4. **Built‑in Tools 内置工具模块**：文件、shell、记忆全部封装在这里，标准化工具接口
5. **Skill Manager 技能管理器【重点模块】**：实现渐进式披露逻辑，Skill生命周期管理，动态注入function‑call schema
6. **Memory Manager记忆管理层**：封装OPENJERRY.md读写、检索、条目格式化，隔离底层文件操作
7. **CLI交互层**：终端交互入口，对话输入输出，日志打印，命令行参数解析
8. 预留抽象接口：后续HTTP/Web服务层占位，现在只定义抽象，不实现业务

> 模块之间依赖清晰，避免循环导入；每个模块职责单一。

## 技术栈约束
- Python >=3.10
- pydantic：数据模型、工具参数schema校验
- pyyaml：配置文件解析
- openai：兼容OpenAI接口客户端（支持兼容各类OpenAI‑API模型）
- click/typer：CLI命令行框架
- 日志库：logging，分级输出日志到控制台+日志文件
- 不引入过重web框架；web相关代码仅预留抽象接口，本期不实现。

## 核心交互逻辑（Agent思考执行闭环）
1. CLI启动，加载config，打印安全警告，初始化技能管理器、记忆管理器；进入交互式对话循环。
2. 用户输入消息送入Agent Core。
3. Agent Core组装基础system prompt（初始只包含内置基础工具schema，**不加载全部Skill**）。
4. 调用LLM，支持Function‑Call：
   - 如果LLM判定任务需要外部Skill能力 → 通过Skill Manager执行渐进披露逻辑，动态追加对应Skill工具schema，重新发起带新工具定义的LLM调用。
   - LLM输出工具调用 → 调度对应工具执行，捕获异常，整理工具返回结果。
   - 将工具执行结果放回对话上下文，继续交给LLM继续思考，多轮迭代直到任务完成。
5. 任务过程中Agent可以主动调用memory工具读写`OPENJERRY.md`长期记忆。
6. 任务结束输出最终回答给终端用户，等待下一轮用户输入。

## 开发交付输出物要求
1. 完整Python项目代码，符合PEP8规范，关键代码增加注释
2. pyproject.toml完整依赖声明
3. README.md文档：项目介绍、安装步骤、配置说明、CLI使用示例、Skill编写教程、安全风险提示
4. 至少1个最小示例Skill放在`./skills`目录，演示如何开发自定义技能
5. .gitignore文件，忽略日志、缓存、本地配置等
6. 启动入口脚本：如 `python -m openjerry` 直接进入cli交互

## 重要约束与注意事项
1. 严格落实 Skills「渐进式披露」，禁止程序启动直接加载所有Skill全部塞入system prompt，这是本项目核心特性。参考agentskills.io核心理念实现。
2. 文件路径安全校验：内置工具防止跳出`./workspace`访问外部系统文件；记忆文件`OPENJERRY.md`除外。
3. 本版本**不实现沙箱**，Shell直接宿主执行，必须在文档和程序启动时显著提示安全风险。
4. 优先保障CLI完整可用；Web/App只做架构预留，本期不开发业务功能。
5. 错误处理完善：文件不存在、命令执行失败、LLM接口报错，给用户可读提示，不要直接抛出原始异常堆栈。
6. 长期记忆是markdown普通文本，允许用户手动编辑，程序不能破坏原有人工手写内容，追加模式优先。