feat: files built-in plugin, doc rewrite, architecture cleanup

- Add files plugin as built-in (internal/plugins/files/) with read/write/edit/ls tools,
  supporting overwrite/append/insert/create modes and offset/limit segmented reading
- Rewrite README.md with core domain separation and three-layer memory highlights
- Rewrite docs/OVERVIEW.md with per-subsystem file path references
- Rewrite docs/ARCHITECTURE.md (783→~300 lines), merge redundant sections
- Clean docs/PLUGIN_DEV.md: remove emoji, simplify SDK examples
- Fix provider Model pollution in LuaAdaptedProvider.Chat()
- Fix executeToolCall to return actual error vs quiet not-found
- Fix plugin.Open path caching with SHA256 temp-path workaround
- Add knowledge/homeagent_architecture demo entry
- Add config/personal/personal.md identity configuration

docs/OVERVIEW.md

@@ -1,87 +1,72 @@
-# HomeAgent — 你的 24/7 智能管家
+# HomeAgent — 项目概览
 
-## 这是做什么的？
+## 这是什么
 
-HomeAgent 是一个**持续运行的个人智能管家**。它像一个随时在线的大脑，你可以通过聊天跟它交流，让它帮你记住事情、查询知识、设置提醒、执行任务。
+HomeAgent 是一个持续运行的个人智能 Agent 框架。
 
-## 核心目标
+核心架构：一个长时间运行的内核进程（`homed`），通过插件系统接入各种 IO 通道（QQ、Web、命令行等）。内核负责 LLM 调用编排、记忆管理、知识检索；插件负责所有外部 IO——收发消息、执行文件操作、搜索网络等。
 
-| 目标 | 说明 |
-|------|------|
-| **永远在线** | 启动后持续运行，不像普通聊天软件需要每次打开 |
-| **真正记住你** | 它不会每次对话都"失忆"——它会积累对你的了解，记住你的喜好、关系网和重要信息 |
-| **隐私可控** | 所有数据存储在你自己的设备上（本地数据库），你也可以选择使用自己的 API 密钥 |
-| **能力可扩展** | 通过"插件"添加新能力——就像手机装 App 一样 |
+### 核心创新
 
-## 谁需要它？
+**核心域与应用域分离** — 这是首个明确提出这一划分的 Agent 框架。内核（核心域）不做任何 IO，所有 IO 能力归属插件（应用域）。边界通过 PluginSDK 明确定义：
+- 插件向内核注册工具（Tool），供 LLM 调用
+- 插件挂入处理管道（Stage），在各阶段拦截/改写消息流
+- 插件订阅/发布事件（Event），松耦合通信
+- 插件通过 IO API 排队或打断投递输入
 
-- **想有个私人助理** — 帮你记待办、定时提醒、管理联系人
-- **重视隐私的用户** — 数据全在本地，不经过第三方云服务
-- **开发者和技术爱好者** — 可以自己编写插件来扩展功能
-- **想探索 AI Agent 的人** — 一个真实可运行的 Agent 系统，不只是 API 调用
+这一划分的意义：内核保持纯粹（零 IO，只做编排和记忆），插件保持灵活（各司其职，热加载），互不污染。
 
-## 它能做什么？
+**三层记忆架构** — 解决 Agent 长期运行的记忆衰减：
+- **Context 层**：内存中 TF-IDF 评分的事件窗口，实时维护最近上下文，低相关性事件自动下沉到下一层
+- **Document 层**：JSON 文件 + TF-IDF 向量索引的临时记忆，支持显式提交和隐式归档，冷数据蒸馏到 Graph
+- **Graph 层**：SQLite 图数据库，持久化实体（entities）和关系（relations），BFS 遍历召回，蒸馏管道从对话中提取三元组
 
-### 🧠 记忆
-- **记住你是谁** — 你的名字、喜好、重要日期
-- **记住人际关系** — "张三是我同事，李四是我的朋友"
-- **长期积累** — 聊得越多，它越了解你
+三层递进：上下文 → 冷归档 → 长期图记忆，确保 Agent 长时间运行不退化。
 
-### 📚 知识
-- 你可以主动教它知识（"公司的休假制度是……"）
-- 它会在需要时检索相关知识
+## 它实际做了什么
 
-### ⏰ 定时提醒
-- "5分钟后提醒我喝水"
-- 倒计时结束后它会主动通知你
+代码位于 `/home/program/TrueAgent`，Go 语言实现。
 
-### 🔌 可扩展（插件）
-- **Web 控制台** — 在浏览器中管理和配置（7 标签页 SPA）
-- **命令行** — 通过终端快速交互
-- **健康检查** — 自动检测系统各组件状态，LLM 驱动故障排查
-- **更多能力** — 开发者可以写插件接入任何服务
+**内核** (`internal/agent/core/agent.go`)：
+- 维护一个消息循环（`eventLoop`），从 IO 层排队接收输入
+- 每次输入走完整的处理管道：记忆召回 → 人格注入 → LLM 调用 → 工具执行 → 输出发送
+- LLM 调用通过 Provider 接口抽象，支持 8 个 LLM 源自动降级
+- 上下文管理（`context.go`）基于 TF-IDF 评分，自动剪枝低相关性事件
 
-## 它是如何工作的？（简述）
+**记忆系统** (`internal/memory/`)：
+- **GraphDB** (`graph.go`) — SQLite，entities + relations 表，BFS 遍历
+- **Document Store** (`document/doc.go`) — 临时记忆，JSON 文件 + TF-IDF 向量索引，消费即删
+- **Text Memory** (`text/text.go`) — 原始对话日志，JSONL 文件轮转
+- **Social Store** (`social/social.go`) — 人格特质 + 关系网，包装 GraphDB
+- **Memory Indexer** (`indexer.go`) — 自动将 GraphDB 实体向量化，用户输入时召回注入 system prompt
 
-```
-你（通过聊天软件/终端/网页）
-        │
-        ▼
-    HomeAgent 内核 ←→ 插件（能力扩展）
-        │
-        ▼
-    本地存储（你的数据只在你这里）
-```
+**知识库** (`internal/knowledge/knowledge.go`)：
+- 文件系统目录 `knowledge/<name>/content.md`
+- TF-IDF 向量搜索，独立于记忆系统的索引实例
+- LLM 通过 `knowledge_search` / `knowledge_create` / `knowledge_list` 三个工具操作
 
-- **内核** 是"大脑"——负责理解你说什么、调用什么能力、记住什么
-- **插件** 是"手脚"——负责收发消息、设置定时器、连接外部服务等
-- **所有数据存本地** — 你的对话、记忆、配置都保存在你自己的设备上
+**插件系统** (`internal/plugin/`)：
+- 内置插件：Go `init()` 自注册，编译进内核
+- 外部插件：Go `-buildmode=plugin` 编译为 `.so`，通过 `plugin.Open` 动态加载
+- PluginSDK (`internal/plugin/sdk/`) 定义三通道：RegisterTool / RegisterStage / Subscribe
+- 阶段钩子 7 个：on_input → pre_action → post_action → before_toolcall → after_toolcall → before_output → after_output
 
-## 和普通 AI 聊天有什么区别？
+**LLM Provider** (`internal/agent/api/provider.go`)：
+- Provider 接口：Name / Chat / ChatStream
+- 三种实现：OpenAIProvider（标准 OpenAI API）、OllamaProvider（本地）、LuaAdaptedProvider（Lua 胶水适配）
+- LuaAdapter 位于 `internal/lua/adapters/`，每个 LLM 源对应一个 `.lua` 脚本
+- 内置 8 个适配器：deepseek / openai / anthropic / gemini / mistral / groq / github / ollama
 
-| | 普通 AI 聊天 | HomeAgent |
-|---|---|---|
-| 记忆 | 每次对话独立，不记得你 | 长期记忆，越来越了解你 |
-| 持续运行 | 关掉就没了 | 7×24 在线 |
-| 主动能力 | 只能回复问题 | 能设定时器、主动提醒 |
-| 可扩展 | 固定能力 | 插件系统，可无限扩展 |
-| 数据隐私 | 上传到云服务 | 本地存储，完全可控 |
-
-## 快速体验
-
-```bash
-# 启动（需要 DeepSeek API 密钥）
-DEEPSEEK_API_KEY="sk-xxx" ./homed -data /tmp/ha
-
-# 在另一个终端聊天
-echo "你好，请记住我喜欢喝咖啡" | ./waiter
-```
+**WebUI** (`internal/plugins/webui/`)：
+- 嵌入式 SPA 仪表盘（`dashboard.html` 通过 `//go:embed` 打包）
+- REST API：状态查询、配置管理、记忆操作、知识库管理、插件管理
+- 兼容 OpenAI API 格式的 `/v1/chat/completions` 端点
+- SSE 事件流 `/api/v1/chat/events`
 
 ## 项目状态
 
-HomeAgent 正在积极开发中。核心功能已可运行，插件系统和开发者 API 已就绪。
+核心功能已可运行。插件系统和 SDK 已就绪，可独立开发外部插件。
 
----
-
-*想参与开发？查看 [PLUGIN_DEV.md](PLUGIN_DEV.md) 插件开发指南。*
-*了解技术架构？查看 [ARCHITECTURE.md](ARCHITECTURE.md)。*
+- 内置插件：webui / cli / timer / cmd / mcp / agentcli / healthcheck / pluginmgr / openclaw / files
+- 外部插件示例（SDK 仓库 `example/`）：qq / files / web / memo
+- 打包分发：`.hmap` 插件包格式，通过 WebUI 安装