项目定位
- 产品定位：轻量级 AI 编程助手
- 目标用户：编程入门新手、初级开发工程师、小微团队或独立开发者
- 核心价值：用户无需手动复制粘贴代码，通过一句自然语言，Agent 就能自主完成「代码定位 - 修改 - 编译测试 - 结果反馈」的全闭环，改完的代码经过本地环境校验，而非大模型的空谈幻觉
功能列表
目前需要的功能
- 受控 Bash 执行能力：让 Agent 能运行编译、测试、项目启动等终端命令，是核心执行手脚
- 精准文件读写能力：让 Agent 能读取指定代码、精准修改，是核心操作能力
- 语义代码搜索能力：让 Agent 在海量代码里快速定位目标函数、变量、报错位置，避免全文件读入浪费 Token
- ReAct 决策引擎：驱动 Agent「思考 - 行动 - 反馈」的核心循环，是 Agent 的大脑
- 上下文 Token 剪枝：防止连续对话导致 Token 溢出、程序崩溃、模型费用暴增
目前暂时不需要的功能
- 开发web界面：非必须，且拖慢团队进度
- 不引入向量数据库与RAG：开发轻量级AI编程助手，优先考虑的是解决精准检索、用户开箱即用等问题，引入RAG一般是在代码库规模大、用户需要AI记住编码习惯以及需要RAG增强生成，不符合当前产品定位，反而还可能出现幻觉、token消耗大、资源占用高等问题
架构设计
采用单进程 ReAct 循环架构，逻辑极简、链路清晰、易开发、易调试：
1.输入层：监听终端命令行输入，接收用户的自然语言需求，处理终端交互指令
2.会话管理层：维护对话历史、工具执行结果、任务进度，负责上下文的拼接、Token 长度校验与剪枝，保证给模型的输入符合要求
3.决策层（核心大脑）：基于 System Prompt、用户需求、历史上下文，通过 LLM 输出决策，判断下一步要调用的工具、传入的参数，实现 ReAct 思考循环（不超过最大迭代次数限制，且有重复操作检测、显式任务清单）
4.工具执行层（核心手脚）：封装好的原子化工具集（bash/read/write/grep），接收决策层的指令，执行本地文件操作、终端命令执行，返回执行结果 / 报错信息
5.反馈层：把工具执行的结果（成功 / 报错）整理后，回传给 LLM，进入下一轮决策循环，直到模型判定任务完成，或达到最大迭代次数强制停止
链路技术栈（来源于opencode、claude code分析，适配了Go语言）：
1. 环境隔离层 (Execution Sandbox)
轻量安全隔离：
- 路径白名单：只允许操作当前目录及子目录，禁止访问../上级目录、系统敏感目录
- 命令黑名单：禁止执行rm -rf、format、mkfs等高危命令
- 用 Go 原生 os/exec + github.com/creack/pty 轻量伪终端，支持 npm test 等实时交互场景，结合 context.WithTimeout 做超时控制（默认 60 秒），不用 Docker 容器化
迭代方案:
- 当用户群体扩展至专业开发者、需要强环境隔离时，再引入 Docker 容器化，通过 github.com/docker/docker/client 调用 Docker API 实现动态容器创建与文件同步
2. 交互与协议层 (Interaction & Protocol)
Go 原生 HTTP + 极简结构体通信：
- 直接调用 Claude API 原生 HTTP 接口，用标准库 net/http 发起请求、encoding/json 解析响应，不用第三方 AI SDK（Go 生态 AI SDK 成熟度有限，原生调用更可控）
- 不用自研 ACP/MCP 协议与状态机，用简单的 for 循环 + channel 同步工具执行结果，任务状态用内存中的 TodoList 结构体管理（MVP 阶段无需持久化）
迭代方案：
- 当需要对接 IDE 插件、多端协同功能时，再引入 ACP/MCP 协议，通过 Go 标准库 net/rpc 或第三方 gRPC 库实现标准化通信；
3. 工具链与感知层 (Perception & Tools)
嵌入 ripgrep + 精准文件读写：
- 语义搜索：用 go:embed 将 ripgrep 二进制嵌入 Go 程序，运行时释放到临时目录调用，解析其 --json 输出提取文件路径、行号，不用 LSP 客户端集成
- 精准文件读写：用标准库 os + bufio 实现 ReadLines（指定行范围读取，避免全文件读入）、ReplaceLines（行级替换，修改前自动备份原文件），所有路径用 path/filepath 处理跨平台兼容，不用 AST 解析
迭代方案：
- 当需要深度代码理解时，再引入 LSP 客户端（用 github.com/sourcegraph/go-lsp），结合 Go 标准库 go/ast（仅支持 Go 语言）或第三方库做简单语义解析；
4. 决策与规划层 (Reasoning & Planning)
- 核心技术点 ：ReAct 循环、Plan-and-Execute 模式、内存/快照管理。
- 核心作用 ：分解复杂任务，处理执行失败后的回滚与重试。
- 标杆项目实现 ：
- OpenCode ：在 src/session 中实现重试机制（ retry.ts ）与版本回滚（ revert.ts ），利用 SQLite 记录完整的操作 Trace。
- 落地注意 ：纯 ReAct 容易陷入死循环，必须引入 todo.ts 类似的显式任务清单模块。
项目定位
功能列表
目前需要的功能
目前暂时不需要的功能
架构设计
采用单进程 ReAct 循环架构，逻辑极简、链路清晰、易开发、易调试：
1.输入层：监听终端命令行输入，接收用户的自然语言需求，处理终端交互指令
2.会话管理层：维护对话历史、工具执行结果、任务进度，负责上下文的拼接、Token 长度校验与剪枝，保证给模型的输入符合要求
3.决策层（核心大脑）：基于 System Prompt、用户需求、历史上下文，通过 LLM 输出决策，判断下一步要调用的工具、传入的参数，实现 ReAct 思考循环（不超过最大迭代次数限制，且有重复操作检测、显式任务清单）
4.工具执行层（核心手脚）：封装好的原子化工具集（bash/read/write/grep），接收决策层的指令，执行本地文件操作、终端命令执行，返回执行结果 / 报错信息
5.反馈层：把工具执行的结果（成功 / 报错）整理后，回传给 LLM，进入下一轮决策循环，直到模型判定任务完成，或达到最大迭代次数强制停止
链路技术栈（来源于opencode、claude code分析，适配了Go语言）：
1. 环境隔离层 (Execution Sandbox)
轻量安全隔离：
迭代方案:
2. 交互与协议层 (Interaction & Protocol)
Go 原生 HTTP + 极简结构体通信：
迭代方案：
3. 工具链与感知层 (Perception & Tools)
嵌入 ripgrep + 精准文件读写：
迭代方案：
4. 决策与规划层 (Reasoning & Planning)