简体中文

GeekAgent 路线图（Day 1 – Day 28）

从零实现一个 Agent（对标 PI / OpenCode）：每天一个功能，永远是最简单的实现。

在线阅读：七天从零实现 GeekAgent

运行

npm run dev -- dayN/index.ts

每日计划

阶段 A：地基（Day 1–4）——能聊，且开始动手

Day	功能	最简单实现说明
1	REPL + 流式多轮对话	readline 逐行读，Chat 类持有 history，OpenAI 兼容接口流式输出
2	工具调用循环	模型返回 tool_call → 执行 → 结果回传 → 继续；第一个工具：当前时间。（例外：允许对 Chat 类做结构性调整以支撑 tool_calls delta）
3	Shell 执行工具	child_process 执行命令，超时 + 输出截断 + 执行前确认（确认逻辑独立成函数，供后续权限模型替换）
4	文件读写工具 + 工具收口	ls/read/glob 只读免确认；write/patch 写入前展示 diff + 确认；顺手为攒下的 7 个工具立统一 Tool 接口 + 注册表 —— Agent 首次闭环「读 → 改 → 验证」

阶段 B：上下文与展示（Day 5–7）——聊得长、分得开、用量看得见

Day	功能	最简单实现说明
5	历史压缩	history 超长时用模型摘要旧文，腾出上下文
6	多会话 + 会话持久化	/new /sessions /open 内存多会话；/save /load 全部会话与当前 ID 落 .geekagent/sessions.json，退出自动保存
7	轻量 TUI + 用量显示	右侧常驻面板实时显示本轮/累计 tokens 与上下文占用比例；流式回复与工具进度行全部进主区并着色。Alt 屏 + 双栏整帧重绘

阶段 C：安全与权限（Day 8）——敢动手也兜得住

Day	功能	最简单实现说明
8	权限模型 + 目录隔离 + 敏感信息保护 + 撤销	工具级策略（ask/allow/deny）与允许访问的根目录由 .geekagent/GeekAgent.json 配置；文件工具只允许在根目录内读写，工具结果自动屏蔽 KEY 类环境变量；写文件前备份最近状态，/undo 恢复

阶段 D：能力进阶（Day 9–12）——更像一个真正的 Agent

Day	功能	最简单实现说明
9	任务规划器 + 子 Agent 拆分	维护 TODO 列表逐步执行，/todos 查看；大任务拆成子任务串行执行（简单 pipeline，非并行）
10	项目指令 + 可检索长期记忆	项目根 AGENTS.md 全量注入 system prompt；运行时重要结论写入 memory 文件，跨会话按关键词搜索复用
11	技能系统	skills/ 目录 = 一组 system prompt + 工具集合，/use <name> 按需加载
12	代码搜索 + Web 抓取	search 工具（ripgrep 风格）仓库内检索；fetch 网页转 markdown，让模型看见外面的世界

阶段 E：记忆与知识库（Day 13–14）——记得住、读得懂

Day	功能	最简单实现说明
13	记忆升级（BM25 分块检索 + 自动唤起）	memory_search 从「整条关键词包含」升级为「按窗口切块 + BM25 打分」，长条目也能精确命中段落；每轮把用户原话切 bigram 自动检索，相关记忆直接拼进 system prompt，模型不用自觉去查
14	轻 RAG 知识库	rag_add 批量采集（内部 fetch 全文落盘、不经模型上下文）→ 切块 → 复用 Day 13 的 BM25 打分 → rag_search 按问检索带来源；/rag 命令离线建库

阶段 F：生态互联（Day 15–16）——工具不必自己写

Day	功能	最简单实现说明
15	MCP 工具接入	.geekagent/mcp.json 声明 server；启动时 spawn 子进程，在 stdio 上按行收发 JSON-RPC：initialize 握手 → tools/list 拉工具 → 以 mcp_<服务>_<工具> 注册进 Day 4 注册表；调用转发 tools/call，默认 ask 确认
16	插件框架 + Web 对话界面	启动时扫描 plugins/*/plugin.ts，通过 PluginContext 注册命令、工具和生命周期钩子；echo 插件演示扩展能力，web 插件启动 HTTP 服务并用 SSE 复用现有对话与工具循环

English

GeekAgent Roadmap (Day 1 – Day 28)

Building an Agent from scratch (benchmarked against PI / OpenCode): one feature per day, always the simplest implementation.

Read online: Build GeekAgent from Scratch in 7 Days

Running

npm run dev -- dayN/index.ts

Daily Plan

Phase A: Foundations (Day 1–4) — Can chat, and starts to act

Day	Feature	Simplest implementation notes
1	REPL + streaming multi-turn chat	readline reads line by line, a Chat class holds history, OpenAI-compatible API streams the output
2	Tool calling loop	Model returns tool_call → execute → send result back → continue; first tool: current time. (Exception: structural changes to the Chat class are allowed to support tool_calls delta)
3	Shell execution tool	child_process runs commands, with timeout + output truncation + confirmation before execution (confirmation logic extracted as a standalone function, ready for a later permission model to replace)
4	File read/write tools + tool consolidation	ls/read/glob are read-only and need no confirmation; write/patch show a diff + confirmation before writing; the 7 accumulated tools get a unified Tool interface + registry — the Agent closes the loop on "read → modify → verify" for the first time

Phase B: Context & Display (Day 5–7) — Chat longer, sessions apart, usage visible

Day	Feature	Simplest implementation notes
5	History compression	When history grows too long, the model summarizes old text to free up context
6	Multi-session + session persistence	/new /sessions /open in-memory multi-session; /save /load persist all sessions and the current ID to .geekagent/sessions.json, auto-save on exit
7	Lightweight TUI + usage display	A persistent right-side panel shows per-turn/cumulative tokens and context usage ratio in real time; streamed replies and tool progress lines all enter the main area with coloring. Alt screen + two-pane full-frame redraw

Phase C: Safety & Permissions (Day 8) — Dares to act, and can contain the blast radius

Day	Feature	Simplest implementation notes
8	Permission model + directory isolation + secret protection + undo	Tool-level policy (ask/allow/deny) and the allowed root directory are configured via .geekagent/GeekAgent.json; file tools only read/write inside the root, tool results automatically mask KEY-type environment variables; the latest state is backed up before writing files, /undo restores

Phase D: Capability Upgrades (Day 9–12) — More like a real Agent

Day	Feature	Simplest implementation notes
9	Task planner + sub-agent decomposition	Maintain a TODO list and execute it step by step, view with /todos; big tasks split into subtasks executed serially (simple pipeline, not parallel)
10	Project instructions + searchable long-term memory	Project-root AGENTS.md fully injected into the system prompt; important runtime conclusions written to a memory file, searched by keyword and reused across sessions
11	Skills system	A skills/ directory = a set of system prompts + tool collections, /use <name> loads on demand
12	Code search + web fetch	A search tool (ripgrep style) searches the repo; fetch turns web pages into markdown, letting the model see the outside world

Phase E: Memory & Knowledge Base (Day 13–14) — Remembers well, reads well

Day	Feature	Simplest implementation notes
13	Memory upgrade (BM25 chunked retrieval + auto recall)	memory_search upgrades from "whole-entry keyword inclusion" to "windowed chunking + BM25 scoring", hitting precise paragraphs even in long entries; each turn slices the user's input into bigrams for automatic retrieval, relevant memories are injected straight into the system prompt — the model doesn't have to remember to search
14	Lightweight RAG knowledge base	rag_add batch collection (internal fetch, full text to disk, bypassing model context) → chunking → reuses Day 13's BM25 scoring → rag_search retrieves with sources by question; the /rag command builds the index offline

Phase F: Ecosystem Connectivity (Day 15–16) — Tools you don't have to write

Day	Feature	Simplest implementation notes
15	MCP tool integration	.geekagent/mcp.json declares servers; at startup spawn subprocesses and exchange line-delimited JSON-RPC over stdio: initialize handshake → tools/list → register as mcp_<server>_<tool> into the Day 4 registry; calls are forwarded as tools/call, defaulting to ask confirmation
16	Plugin framework + web chat UI	At startup scan plugins/*/plugin.ts, register commands, tools and lifecycle hooks through a PluginContext; an echo plugin demonstrates the extension points, a web plugin starts an HTTP service and reuses the existing chat & tool loop over SSE