neo-code产品初期测试报告及评估方向

[Cai-Tang-www]

report.md

用户角度评测

缺失了哪些核心能力 ，本质上不是“类 Codex 的 CLI Code Agent”

从使用场景看，最核心的部分是以下三点：

场景 A：仓库理解

• 帮我看这个项目做什么；
• 找出入口；
• 梳理模块关系；
• 总结某个目录。

场景 B：局部改动

• 修改一个函数；
• 修一个明确报错；
• 增加一个配置项；
• 调整一段逻辑。

场景 C：调试闭环

• 跑测试；
• 看报错；
• 做最小修复；
• 再跑验证。

1）没有代码工作区感知

没有看到任何“扫描项目文件”“理解仓库结构”“读取指定文件”“基于 diff 修改文件”的能力。
也没有文件索引、代码搜索、符号级理解、AST 分析。当前上下文来源只有：

• persona；
• 最近几轮消息；
• 本地历史记忆。

这意味着它不知道自己正在操作哪个项目、哪个语言栈、哪个入口文件。这跟真正的 Code Agent 差距极大。.

2）没有任何工具执行系统

没有 shell、git、test、lint、format、build、run、patch、diff、apply 的工具接口。
ai/provider.go 只有聊天模型和 embedding 模型两个抽象接口。没有 tool schema、没有 function calling、没有命令执行器。.

3）没有代码修改链路

系统不会：

• 打开文件；
• 修改文件；
• 生成 patch；
• 回滚失败修改；
• 比较变更前后内容。

所以它只能“说怎么改”，不能“真的改”。这在 CLI Code Agent 产品里属于核心缺失。

4）没有任务分解 / 计划 / 执行状态

成熟 Agent 至少会有：

• 理解任务；
• 规划步骤；
• 执行工具；
• 观察结果；
• 再规划；

而当前项目没有 plan object、没有 task state、没有 execution journal、没有 step trace。用户输入是直接发给模型。.

5）记忆逻辑与“开发任务记忆”不匹配

现在的记忆存的是：

• user input
• assistant reply
• embedding

这是“聊天记忆”，不是“工程任务记忆”。缺少：

• 当前仓库上下文；
• 已执行命令结果；
• 修改过的文件；
• 失败原因；
• 任务目标；
• 用户偏好（如测试偏好、代码风格、提交规范）。

6）交互对象错位：它看起来像 Code Agent，实则chatbot

缺少很多

• /edit
• /run
• /test
• /diff
• /apply
• /status
• /plan
• 的REPL命令，什么都干不了

7）聊天失败时，错误传播不完整，没有明确error 失败状态

失败时缺乏超时重试/请求中提醒等

复杂指令场景

对复杂请求如：

• “先分析 bug，再运行测试，定位失败，再最小修改修复”
• “先列计划，不要改代码，等我确认再执行”
• “如果测试失败，保留 patch 并给出原因”

当前系统都无能为力，因为没有计划控制、执行控制、审批机制。

AI跑的建议

---

任务理解与意图识别能力差距

成熟代码 Agent 的核心不是“回答问题”，而是“把用户目标转成可执行工作流”。
当前 neo-code 还停留在“把用户输入原样发给模型”的阶段。.

成熟 Agent 会做的事

• 识别这是问答、分析、修改、调试、测试还是重构；
• 判断是否需要先看文件；
• 判断是否需要生成计划；
• 判断能否直接执行；
• 判断风险等级和是否请求确认。

neo-code 当前情况

• 没有任务分类器；
• 没有 planner；
• 没有操作许可层；
• 没有 task state machine。

所以它不能区分：

• “解释这个函数”
  vs
• “修改这个函数”
  vs
• “运行测试并修复”

成熟 Agent 的状态

成熟产品通常会维护多层状态：

1. 会话状态：当前任务是什么；
2. 工作区状态：有哪些文件被查看/修改；
3. 执行状态：命令跑过什么、结果如何；
4. 用户偏好：是否允许自动运行测试、是否偏好最小改动；
5. 历史状态：失败原因与恢复点。

neo-code 当前状态

当前只有：

• persona；
• 最近几轮消息；
• 基于 embedding 的历史问答记忆。

这不是“Agent state”，只是“对话上下文”。.

代码生成 → 修改 → 调试 → 运行闭环能力差距

成熟 Agent 的闭环

一个合格 CLI Code Agent 至少要做到：

1. 读文件；
2. 生成修改；
3. 应用 patch；
4. 运行测试 / lint / build；
5. 获取报错；
6. 二次修复；
7. 输出 diff 与结果。

neo-code 现在只有

• 生成自然语言回复；
• 保存到本地记忆。

工具调用（shell、git、lint、测试等）能力差距

成熟 Agent

会有清晰的工具层，例如：

• shell executor
• file read/write
• git diff/status/commit
• search / grep / ripgrep
• test runner
• formatter / linter
• browser / docs fetch

neo-code

没有任何工具抽象。
ai/provider.go 只有 ChatProvider 和 EmbeddingProvider。工具系统是空白。

模型没有行动能力，只有语言能力。
而 Code Agent 的竞争力本质上来自工具使用能力，不是聊天能力。

安全性、隔离性、权限控制差距

成熟产品会有

• 工作目录限制；
• 工具白名单；
• 命令确认机制；
• 文件写入范围控制；
• 网络权限控制；
• 审计日志；
• 敏感文件保护。

neo-code 当前状态

因为还没有工具层，所以“权限控制”也根本没建立。

最低可用版本（MVP）必须实现的核心功能

一周后要交

---

P0-1：项目工作区感知与文件读取

功能描述

让 Agent 能感知当前仓库，支持：

• 列出文件树；
• 搜索文件；
• 打开文件；
• 截取指定行；
• 读取多个相关文件摘要。

实现目标

最少实现以下工具：

• list_files(path, depth)
• read_file(path, start, end)
• search_code(query/glob)
• summarize_repo()

用户价值

用户第一次才会觉得它是“代码工具”而不是“聊天工具”。
没有这层，后面改代码、调试、架构分析都无从谈起。

---

P0-2：文件修改与 patch 应用能力

功能描述

支持 Agent 对文件进行安全修改：

• 全量覆盖；
• 按块 patch；
• diff 预览；
• 回滚。

实现目标

至少具备：

• write_file(path, content)
• apply_patch(diff)
• show_diff()
• revert_last_change()

优先选择 patch-first 模型，而不是直接整文件覆盖。

用户价值

用户才能真正把它用于“修 bug、改需求、加功能”。

---

P0-3：命令执行闭环（run/test/lint/build）

功能描述

支持 Agent 在受控环境中执行命令，并把结果反馈给模型继续处理。

实现目标

至少支持：

• run_command(cmd, cwd, timeout)
• 捕获 stdout / stderr / exit code
• 可限制白名单命令
• 支持 go test / npm test / pytest / cargo test 等常见工作流

用户价值

没有这个能力，就不可能形成“改完代码→验证结果→继续修复”的闭环。

---

P0-4：任务计划与执行状态面板

功能描述

Agent 在执行前先生成计划，执行时展示当前步骤，失败时记录在哪一步。

实现目标

至少支持：

• 计划生成；
• 当前步骤显示；
• 步骤状态：pending / running / done / failed；
• 最终总结。

用户价值

提高可控性与可信度。
用户知道它“在做什么”，而不是黑盒输出。

---

P0-5：错误恢复与重试机制

功能描述

对网络错误、命令失败、patch 失败等情况做恢复。

实现目标

包括：

• API 超时和重试；
• 工具失败后结构化记录；
• 一键重试当前步骤；
• 命令失败后自动提炼关键信息给模型。

用户价值

早期 demo 最容易输在“不稳定”，不是“不聪明”。
恢复能力比模型智商更早决定可用性。

---

P1-6：上下文管理从“消息轮次”升级为“任务状态”

功能描述

从聊天历史管理，升级为任务导向状态管理：

• 任务目标；
• 已读文件摘要；
• 已执行命令；
• 当前 patch；
• 验证结果。

实现目标

设计 SessionState / TaskState，而不是只靠 []ai.Message。
消息历史只做模型输入层，不做系统真实状态层。

用户价值

长任务不会丢状态，多轮协作会稳定很多。

---

P1-7：模型配置与 Provider 抽象标准化

功能描述

把模型切换从“硬编码白名单 + YAML URL 映射”改成统一注册表。

实现目标

• 模型列表完全配置化；
• provider、model、capability 分离；
• 标注哪些模型支持 chat / tool / embedding / reasoning。

用户价值

便于接更多模型，也能解决当前 /switch 与配置脱节的问题。.

---

P1-8：开发者友好的 CLI 命令体系

功能描述

把当前聊天式命令扩展成真正开发工作流命令。

实现目标

建议最少增加：

• /plan
• /status
• /read <file>
• /edit <file>
• /diff
• /run <cmd>
• /test
• /approve
• /reset-task

用户价值

提高可发现性，降低 prompt 依赖。

---

差异化竞争方向

更现实的差异化方向有 3 个：

方向 1：中文开发者友好

当前 README 与代码注释已偏中文语境。
你可以强化：

• 中文命令帮助；
• 中文错误解释；
• 中文架构分析；
• 国内模型 / 国内 API 兼容。

方向 2：本地可控 / 配置透明

强调：

• 本地 JSON 记忆；
• 本地配置文件；
• 可自定义 persona；
• 可替换 provider。

这比“云端黑盒 Agent”更容易获得一批技术用户。

方向 3：极简 CLI 体验

不是追求全功能，而是追求：

• 安装简单；
• 配置简单；
• 命令少但有效；
• 输出清晰；
• 对 Go / Node / Python 常见项目即插即用。

以下是针对于目前的架构建议

Agent 执行架构（ReAct / Plan & Execute / Tool Use）

建议：短期用 Plan & Execute，长期演进为 Tool-augmented ReAct

为什么不建议一上来纯 ReAct

纯 ReAct 在早期 demo 很容易：

• 乱调用工具；
• 上下文膨胀；
• 状态失控；
• 难以审计。

推荐方案

阶段 1：Plan & Execute

流程：

1. 解析用户意图；
2. 生成计划；
3. 执行第一步；
4. 观察结果；
5. 更新计划；
6. 继续执行。

优点：

• 可控；
• 便于展示给用户；
• 容易插入审批。

阶段 2：带工具的 ReAct

在基础稳定后，引入更细粒度推理-行动循环，但要加：

• step budget；
• tool budget；
• context compaction；
• failure policy。

底层状态设计建议

至少定义：

• SessionState
• TaskState
• PlanStep
• WorkspaceSnapshot
• ExecutionLog
• ToolResult

不要再用单纯 []Message 承载全系统状态。.

---

代码沙箱、文件系统操作、安全隔离方案

文件系统

建议限制在当前工作目录及其子目录中操作。
禁止默认访问：

• ~/.ssh
• .env
• 系统目录
• git credential 文件

命令执行

建议做三级权限模型：

Level 1：安全只读

• pwd
• ls
• find
• rg
• cat

Level 2：开发验证

• go test
• npm test
• pytest
• go build
• npm run lint

Level 3：高风险写操作

• rm
• mv
• git reset
• 任意 shell pipeline
• 网络写操作

默认只开放 L1 + 部分 L2，高风险命令必须确认。

隔离建议

中期可以考虑：

• 进程级超时；
• cwd 限制；
• 环境变量白名单；
• 审计日志；
• patch-first 写文件策略。

---

扩展性、插件化、配置化设计建议

插件化建议

未来把工具能力设计成插件注册：

• File tools
• Shell tools
• Git tools
• Test tools
• Search tools
• Web/docs tools

每类工具声明：

• name
• input schema
• risk level
• timeout
• allowed cwd
• human approval policy

配置化建议

当前配置分成 config.yaml 和 config/models.yaml，方向是对的。
但还应继续拆分：

• providers.yaml
• models.yaml
• tools.yaml
• policies.yaml

这样后续更利于用户自定义。

当前配置层面的明显问题

模型支持列表不应再硬编码在 SupportedModels。
否则配置化永远做不透。.

---

需要做的事有三件

第 1 件事：补齐“读代码能力”

如果连读文件、搜索代码、总结目录都没有，就谈不上后面的代码修改。

本周落地范围

• 增加文件树扫描；
• 增加文件读取；
• 增加代码搜索；
• 增加 repo summary；
• 在 prompt 中自动注入相关文件内容。

成功标准

输入：
“分析这个 Go 项目的架构和核心模块。”
Agent 能基于真实代码输出，而不是泛化空话。

---

第 2 件事：建立计划与状态管理，不再只靠消息历史

为什么最优先

Agent 一旦要执行多步骤任务，没有状态就一定崩。
这件事是后续“改代码”“跑测试”的基础设施。

本周落地范围

• 定义 TaskState；
• 定义 PlanStep；
• 增加 /plan、/status；
• 让每次请求先分类再规划；
• 把“已读文件摘要”放进状态，而不是消息历史。

成功标准

用户可以清晰看到：

• 当前目标是什么；
• 已完成什么；
• 下一步是什么。

---

第 3 件事：接入最小可用工具闭环——文件 patch + 受控命令执行

为什么最优先

这是从“分析工具”迈向“代码 Agent”的分水岭。

本周落地范围

• 支持生成并应用 patch；
• 支持运行受控命令；
• 捕获 exit code/stdout/stderr；
• 把结果回灌给模型继续处理。

成功标准

用户输入：
“修复一个简单 Go 编译错误。”
Agent 至少能：

1. 读文件；
2. 改文件；
3. 跑 go build；
4. 给出最终 diff 和结果。