项目名称：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普通文本，允许用户手动编辑，程序不能破坏原有人工手写内容，追加模式优先。