1024XEngineer · minorcell · Mar 27, 2026 · Mar 26, 2026 · Mar 27, 2026 · Mar 27, 2026
diff --git a/.codecov.yml b/.codecov.yml
@@ -0,0 +1,8 @@
+coverage:
+  status:
+    project:
+      default:
+        target: 80%   # 告诉裁判：整体覆盖率 80% 就给我亮绿灯
+    patch:
+      default:
+        target: 80%   # 告诉裁判：这次 PR 新增的代码覆盖率达到 80% 也给我亮绿灯
diff --git a/AGENTS.md b/AGENTS.md
diff --git a/README.md b/README.md
@@ -1,210 +1,61 @@
 # NeoCode
+NeoCode 是一个基于 Go 和 Bubble Tea 构建的本地 Coding Agent MVP。它把 Provider 防腐层、工具调用闭环、本地会话持久化和沉浸式瀑布流 TUI 组合在一起，用于日常代码理解、修改和终端内协作。
 
-一个基于 Go 的终端对话工具，当前使用根目录 `config.yaml` 作为唯一业务配置文件，并使用结构化 code memory 做记忆召回。
+## 功能特性
+- 基于防腐层的 Provider 架构，当前支持 OpenAI 兼容流式接口，并为 Anthropic、Gemini 预留了扩展位置。
+- ReAct 风格的 runtime 主循环，能够读取模型输出、执行工具调用、回灌结果并继续推理。
+- 瀑布流终端界面，支持流式 transcript、内联工具事件、Slash Command 和会话侧边栏。
+- 本地 YAML 配置、`.env` 加载与并发安全的热更新能力。
+- 本地 JSON 会话持久化，不依赖远端服务即可恢复历史上下文。
+- 文件系统高级工具：读取、写入、搜索、Glob 探测和精准替换。
 
-现在支持：
+## 环境要求
+- Go 1.21 及以上
+- 至少一个可用的模型 Provider API Key，例如 `OPENAI_API_KEY`
 
-1. TUI 对话与流式输出
-2. `/switch` 切换聊天模型
-3. `/provider` 切换模型提供商
-4. 结构化长期记忆检索与写回
-5. session memory 与短期上下文保留
-6. 人设文件注入
-7. 启动时校验环境变量 API Key
-8. `/memory`、`/clear-memory confirm`、`/clear-context`
-9. 工作区目录感知（`--workspace` / `NEOCODE_WORKSPACE` / 当前目录）
-
-## 文档导航
-
-如果你想快速理解项目设计、接口约定、安全机制或团队协作方式，可以优先阅读以下文档：
-
-- [整体架构设计说明](./docs/structure.md)：快速了解项目分层思路、目录结构和模块职责。
-- [架构详细说明文档](./docs/detailed_architecture_guide.md)：深入理解系统目标、核心架构、数据流和后续演进方向。
-- [API 契约书与开发指南](./docs/API_Contract_Guide.md)：了解 `api/proto/chat.proto` 的契约设计和前后端协作边界。
-- [GitHub Actions + Codecov 使用指南](./docs/github-actions-codecov-guide.md)：面向新成员的 CI、测试覆盖率与 PR 检查上手文档。
-- [安全拦截器模块文档](./docs/Security_Interceptor.md)：说明工具执行前的安全校验模型与接口规范。
-- [安全拦截器测试手册](./docs/Security_Interceptor_Test_Manual.md)：整理安全拦截相关测试点与手工验证步骤。
-- [Repository Guidelines](./docs/AGENTS.md)：补充仓库协作约定、目录组织与开发命令说明。
-
-## 配置方式
-
-只需要维护根目录下的 `config.yaml`，并在系统环境变量中设置 API Key。
-
-- 可以先参考 `config.example.yaml`
-- 首次启动时如果 `config.yaml` 不存在，程序会自动创建默认配置
-- API Key 配置方法见下方 `API Key 配置`
-- `ai.api_key` 填写的是环境变量名；留空时会回退到 `AI_API_KEY`
-- 如果 Key 校验失败，可使用 `/apikey <env_name>` 或 `/provider <name>` 调整配置
-- 如果网络异常导致无法确认 Key 是否有效，可使用 `/retry`、`/continue`、`/apikey <env_name>`、`/provider <name>`、`/switch <model>` 或 `/exit`
-- 支持的 provider：`modelscope`、`deepseek`、`openll`、`siliconflow`、`豆包大模型`、`openai`
-- 切换 provider 时会自动切到该厂商默认模型，也可以继续使用 `/switch <model>` 自定义
-
-## API Key 配置
-
-程序会从 `config.yaml` 的 `ai.api_key` 指定的系统环境变量中读取真实 API Key；如果该字段为空，则默认读取 `AI_API_KEY`。`config.yaml` 不存储真实密钥。
-
-例如：
-
-```yaml
-ai:
-  provider: "openll"
-  api_key: "MY_TEAM_API_KEY"
-  model: "gpt-5.4"
-```
-
-这表示程序会读取系统环境变量 `MY_TEAM_API_KEY`。
-
-Windows 永久生效：
-
-```powershell
-setx AI_API_KEY "your-api-key"
-```
-
-设置后请关闭并重新打开终端，再验证是否生效：
-
-```powershell
-echo $env:AI_API_KEY
-```
-
-Windows 当前终端临时生效：
-
-```powershell
-$env:AI_API_KEY="your-api-key"
-```
-
-CMD 当前终端临时生效：
-
-```cmd
-set AI_API_KEY=your-api-key
-```
-
-配置完成后启动项目：
+## 快速开始
+1. 克隆仓库。
+2. 准备 Provider 的 API Key，可以通过环境变量或 NeoCode 托管的 `.env` 文件提供。
+3. 运行应用：
 
 ```bash
-go run ./cmd/tui
+go run ./cmd/neocode
 ```
 
-也可以显式指定工作区目录（工具读写和工作记忆都会基于该目录）：
+首次启动时，NeoCode 会在当前用户主目录下创建自己的托管目录、默认配置和会话存储结构。
 
-```bash
-go run ./cmd/tui --workspace ./
-```
+## Slash Command
+- `/set url <url>`：更新当前选中 Provider 的 Base URL。
+- `/set key <key>`：将当前 Provider 的密钥写入托管 `.env` 并立即重新加载。
+- `/model`：打开交互式模型选择列表。
 
-或者通过环境变量指定：
+## 开发与验证
+在提交 Pull Request 前建议至少执行以下命令：
 
 ```bash
-set NEOCODE_WORKSPACE=F:\\Qiniu\\test1
-go run ./cmd/tui
-```
-
-工作区解析优先级：`--workspace` > `NEOCODE_WORKSPACE` > 启动时当前目录。
-
-示例：
-
-```yaml
-app:
-  name: "NeoCode"
-  version: "1.0.0"
-
-ai:
-  provider: "openll"
-  api_key: "AI_API_KEY"
-  model: "gpt-5.4"
-
-memory:
-  top_k: 5
-  min_match_score: 2.2
-  max_prompt_chars: 1800
-  max_items: 1000
-  storage_path: "./data/memory_rules.json"
-  persist_types:
-    - "user_preference"
-    - "project_rule"
-    - "code_fact"
-    - "fix_recipe"
-
-history:
-  short_term_turns: 6
-  max_tool_context_messages: 3
-  max_tool_context_output_size: 4000
-  persist_session_state: true
-  workspace_state_dir: "./data/workspaces"
-  resume_last_session: true
-
-persona:
-  file_path: "./persona.txt"
-```
-
-说明：
-
-- `ai.api_key`：API Key 对应的环境变量名；为空时回退到 `AI_API_KEY`
-- `ai.provider`：当前模型提供商，支持 `modelscope`、`deepseek`、`openll`、`siliconflow`、`豆包大模型`、`openai`
-- `ai.model`：当前 provider 使用的模型名；执行 `/provider <name>` 时会自动切到该厂商默认模型，也可通过 `/switch <model>` 覆盖
-- `memory.storage_path`：长期结构化记忆文件
-- `memory.persist_types`：允许持久化的结构化记忆类型
-- `memory.min_match_score`：最低召回分数
-- `memory.max_prompt_chars`：记忆注入 prompt 的总字符上限
-- `history.short_term_turns`：保留最近多少轮上下文
-- `history.persist_session_state`：是否按 workspace 持久化当前工作现场
-- `history.workspace_state_dir`：workspace 会话状态文件保存目录
-- `history.resume_last_session`：启动时是否展示恢复摘要
-- `persona.file_path`：启动时加载的人设文件
-
-## Memory 设计
-
-当前 memory 使用纯结构化规则召回，不使用 embedding 或向量相似度。系统会将长期结构化记忆写入 `memory.storage_path`，并在当前进程内维护 session memory。主要包括：
-
-- `user_preference`：用户长期偏好
-- `project_rule`：项目级约定、目录结构、常用命令、配置规则
-- `code_fact`：明确的代码事实、文件职责、模块位置
-- `fix_recipe`：排障经验、常见报错与修复方式
-- `session_memory`：当前会话里仍有价值的临时 coding 信息
-
-召回顺序会优先考虑长期记忆中的用户偏好、项目规则、代码事实、修复经验，再补充 session memory。
-
-此外，working memory 现已支持按 workspace 保存会话快照。程序会记录当前目标、最近完成动作、下一步、最近文件和最近几轮对话，并在下次进入同一工作区时恢复这份现场。
-
-## 运行
-
-```bash
-go run ./cmd/tui
-```
-
-如果只想验证服务组装：
-
-```bash
-go run ./cmd/server
-```
-
-## 可用命令
-
-- `/provider <name>`：切换当前模型提供商
-- `/apikey <env_name>`：切换当前读取的 API Key 环境变量名并立即校验
-- `/switch <model>`：切换当前聊天模型
-- `/memory`：查看长期记忆和 session memory 状态，以及各类型统计
-- `/pwd` 或 `/workspace`：查看当前工作区目录
-- `/clear-memory confirm`：确认后清空长期结构化记忆
-- `/clear-context`：清空当前短期上下文和 session memory
-- `/help`：查看帮助
-- `/exit`：退出程序
-
-## 相关文件
-
-- `config.yaml`：主配置文件
-- `config.example.yaml`：配置模板
-- `data/memory_rules.json`：长期结构化记忆文件
-- `data/workspaces/<workspace-hash>/session_state.json`：按工作区保存的当前工作现场
-- `persona.txt`：人设内容
-
-## 安全与本地文件
-
-- `config.yaml` 中的 `ai.api_key` 仅保存环境变量名，不写入真实密钥
-- `ai.api_key` 为空时默认读取系统环境变量 `AI_API_KEY`
-- `config.yaml` 已在 `.gitignore` 中忽略，不应提交真实密钥
-- `data/` 已在 `.gitignore` 中忽略，本地记忆不会默认入库
-- `.env` 不再是主配置来源，如保留仅用于个人兼容场景
-
-## 测试
-
-- 运行测试：`go test ./...`
-- 代码格式化：`go fmt ./...`
+gofmt -w ./cmd ./internal
+go test ./...
+```
+
+## 架构概览
+- `internal/config`：负责 YAML 加载、`.env` 集成、默认值管理和并发安全更新。
+- `internal/provider`：将厂商特定的请求和流式响应抹平成统一领域模型。
+- `internal/runtime`：负责事件总线、ReAct loop、Provider 动态构建和会话持久化。
+- `internal/tools`：提供工具注册表以及各类具体工具实现。
+- `internal/tui`：负责终端交互体验，以及 runtime 事件到 Bubble Tea 消息的桥接。
+
+## 目录结构
+```text
+.
+|-- cmd/neocode
+|-- docs
+|-- internal/app
+|-- internal/config
+|-- internal/provider
+|-- internal/runtime
+|-- internal/tools
+`-- internal/tui
+```
+
+## 当前状态
+NeoCode 目前聚焦于 MVP 闭环：本地对话、工具调用、Session 持久化和终端交互体验。当前版本正在继续向“高质量开源项目”标准收敛，重点补强文档、测试覆盖率和工具能力。
diff --git a/agents.md b/agents.md
@@ -0,0 +1,43 @@
+# NeoCode
+## Name
+NeoCode
+## Description
+NeoCode 是一个基于 Go 和 Bubble Tea 构建的本地编码 Agent。它在终端中运行 ReAct 闭环，可以对话、调用工具、持久化会话，并以流式方式展示推理结果。
+## Capabilities
+- 通过 provider 无关的 runtime 读取、理解并操作当前工作区代码。
+- 调用文件系统、Shell 和 Web 工具完成读取、写入、搜索、精准修改等任务。
+- 将会话历史持久化到本地，并在 TUI 侧边栏中恢复旧会话。
+- 在瀑布流终端界面中实时展示模型输出和工具执行过程。
+- 通过 Slash Command 在运行时更新 Provider URL、API Key 和当前模型。
+## Tools
+- `filesystem_read_file`：读取工作区内的文件内容。
+- `filesystem_write_file`：创建或覆盖工作区内的文件。
+- `filesystem_grep`：在工作区内按关键字或正则搜索代码片段。
+- `filesystem_glob`：按通配模式列出文件路径，帮助 Agent 探测代码树结构。
+- `filesystem_edit`：基于唯一匹配块做精准替换，避免整文件重写。
+- `bash`：在限定工作区内执行 Shell 命令，并支持超时控制。
+- `webfetch`：按上下文超时规则抓取远程 HTTP 内容。
+## Project Structure
+- `cmd/neocode`：CLI 入口。
+- `internal/config`：配置模型、YAML 加载、环境变量管理和并发安全访问。
+- `internal/provider`：Provider 接口、领域模型以及各模型厂商适配器。
+- `internal/runtime`：事件流、Session 持久化、Prompt 编排与 ReAct 主循环。
+- `internal/tools`：工具契约、注册表和具体工具实现。
+- `internal/tui`：Bubble Tea 状态机、渲染层、Slash Command 和事件桥接。
+## How To Work With This Project
+- 从 runtime 边界开始理解系统。TUI 不能直接调用 provider 或 tools。
+- 将 `internal/provider` 视为防腐层。runtime 只能操作 provider 标准消息和工具调用结构。
+- 一切配置修改都必须经由 `ConfigManager`，以保证并发安全。
+- API Key 不得写入 YAML，只允许在配置中保存环境变量名，并在运行时解析真实值。
+- 对 config、provider streaming、runtime orchestration 或 tools 的改动，优先补充或更新测试。
+## Setup Commands
+- 启动应用：`go run ./cmd/neocode`
+- 运行测试：`go test ./...`
+- 格式化代码：`gofmt -w ./cmd ./internal`
+## Interaction Tips
+- 普通编码任务和仓库问题可以直接用自然语言输入。
+- 本地控制命令统一通过 Composer 中的 Slash Command 触发：
+  - `/set url <url>`
+  - `/set key <key>`
+  - `/model`
+- 第一次启动应用后，NeoCode 会自动创建自己的托管目录、配置文件和会话存储目录。