Nano

Imported from Devi1Aki/Nano (AGENTS.md). Install upstream with npx skills add Devi1Aki/Nano. Copyright stays with the author.

AGENTS.md

仓库给 Agent / 新线程使用的首读入口。详细行为描述见 docs/agents-reference.md。

信息优先级

1. 代码实际行为 > 2. AGENTS.md > 3. README.md > 4. ROADMAP.md > 5. CLAUDE.md

ROADMAP.md 代表演进方向，不代表已交付。

项目快照

• 项目名：Nano
• 定位：面向商业使用的 Java Agent CLI 产品，对标 Claude Code
• 已交付 24 期（ReAct → Plan+DAG → Memory → RAG → Multi-Agent → HITL → 并行工具 → 多模型 → 联网 → MCP 核心 → MCP 高级 → 长上下文 → Chrome DevTools → CDP 会话复用 → Skill → TUI → LSP 诊断 → Side-Git 快照 → Prompt 分层 → Runtime API → 图片输入 → Trace → Eval → Eval 隔离与稳定性采样）
• 下一步：Eval headless/CI 退出码；OAuth / sampling / recovery 作为后续 MCP 增强
• Banner 版本：v1.4.0，Maven 产物：nano-1.4.0.jar

运行前提

• Java 17+ / Maven
• 至少一个 API Key：GLM_API_KEY / DEEPSEEK_API_KEY / STEP_API_KEY / KIMI_API_KEY

常用命令

cp .env.example .env
mvn clean package        # 默认跳过测试，优先产出可手工验收 jar
java -jar target/nano-1.4.0.jar
mvn test -Pquick          # 常规回归
mvn test -Pphase16-smoke  # TUI 相关
mvn test -Dtest=XxxTest -DskipTests=false   # 针对性
mvn test -DskipTests=false                  # 全量回归

架构概览

三条主执行路径，共享 ToolRegistry / MemoryManager / SnapshotService：

内置工具 9 个：read_file / write_file / list_dir / execute_command / create_project / search_code / web_search / web_fetch / revert_turn

MCP 动态工具：mcp__{server}__{tool}（+ resources 虚拟工具）

仓库结构

src/main/java/com/nano/
├── agent/       Agent.java, PlanExecuteAgent.java, SubAgent.java, AgentOrchestrator.java
├── cli/         Main.java, CliCommandParser.java, PlanReviewInputParser.java
├── browser/     BrowserSession, BrowserGuard, SensitivePagePolicy
├── llm/         GLMClient, DeepSeekClient, StepClient, KimiClient
├── context/     ContextProfile, ContextMode, TokenUsageFormatter
├── memory/      MemoryManager, ConversationHistoryCompactor, LongTermMemory
├── plan/        Planner, ExecutionPlan, Task
├── rag/         CodeIndex, CodeRetriever, VectorStore, CodeChunker
├── lsp/         LspManager, LspDiagnosticFormatter
├── prompt/      PromptAssembler, PromptContext, PromptRepository
├── image/       ImageReferenceParser
├── runtime/     api/ (RuntimeApiServer) + task/ (DurableTaskManager)
├── trace/       TraceStore, TraceContext, TraceFormatter
├── eval/        BenchmarkCorpus, EvalWorkspace, EvalCheckRunner, EvalRunner, LlmCaseJudge
├── snapshot/    SideGitManager, SnapshotService
├── tool/        ToolRegistry
├── mcp/         McpClient, McpServerManager, transport/, resources/, mention/
├── hitl/        HitlToolRegistry, ApprovalPolicy, TerminalHitlHandler
├── web/         SearchProvider, WebFetcher, HtmlExtractor, NetworkPolicy
├── policy/      PathGuard, CommandGuard, AuditLog
├── skill/       SkillRegistry, SkillContextBuffer, SkillIndexFormatter
└── render/      Renderer, InlineRenderer, PlainRenderer, RendererFactory

启动与 inline 渲染当前约定：

• 开屏 Banner 使用大字符块 NANO、小猫头像和酒红色闭合边框；首屏只展示模型、工具总数、MCP、Skill、ReAct 状态和三条 getting-started tips，不再把 MCP server 明细刷成启动日志。
• inline 模式使用 JLine 4 的 LineReader 编辑能力，默认提示符是 * ，右提示显示 message / @path / @image。
• 默认 CLI 启动路径应先 Renderer.start() 并初始化底部 dock；inline 首屏不要在 readLine 前裸写 stdout，而是通过 InlineRenderer.installStartupScreen(...) 挂到 LineReader.CALLBACK_INIT，首次进入输入时用 printAbove 一次性显示完整 Banner + tips，避免 logo 被 LineReader 首次重绘滚出可视区域。
• BottomStatusBar 现在是 JLine Status 托管的底部 dock：由 JLine 维护滚动区域和状态行位置，不再手写 \n / moveUp / CLEAR_TO_EOS 清屏。输入期会把 LineReader 光标定位到 dock 上方一行，让 * 输入行和 Status 同处底部区域；dock 保留两类信息：上层模式 + MCP/Skill 摘要，下层 Auto Model / model / phase / ctx 百分比与 token / cost / elapsed / cwd。
• 普通任务提交后，Main 会把本轮原始用户 prompt 以暗色整行块写回 transcript：输入态左提示仍是 * ，提交回显左提示改为 >；单行输入只占一行，不额外追加空白行。随后再展开 MCP resource / 本地 @path 并进入 Agent；不要只依赖 JLine 提交行残留，否则 activity 重绘或 dock 刷新可能让用户提示词从可见历史里消失。
• ReAct LLM 调用期间，inline renderer 使用固定高度 live thinking 区动态显示 Thinking... 和灰色竖线 reasoning 预览；该区域只能清理自己刚打印的几行，不能用独立 JLine Display.update() / CLEAR_TO_EOS 向上覆盖 transcript。content 或 tool call 开始前先清掉 live 区，再把完整 reasoning 引用块落到正文区，正文回答用低调标记起始，不再刷强标题。
• 交互期输出应优先走 Renderer.stream()；Main、PlanExecuteAgent、Planner、AgentOrchestrator 都支持把输出流接到 inline renderer，避免直接争抢 stdout。CodeIndex 的索引进度通过 ProgressListener 注入，/index 应绑定到当前 renderer 输出流。
• Phase 22 开始，InlineRenderer 可绑定当前 LineReader；当 LineReader.isReading() 为 true 时，Renderer.stream() 的完整行输出优先通过 LineReader#printAbove 显示在输入行上方，未绑定 / 非读取态 / 测试路径回退到原 PrintStream。
• ReAct 正常结束后不再把 📊 Token: ... 打进正文区；token/cost/elapsed 会保留在底部强状态行，phase 回到 idle。
• 每轮 CLI Agent 任务通过 TraceContext 建立独立 trace；TracingLlmClient 记录模型耗时与 token，ToolRegistry.executeTools() 记录工具耗时与状态，完整内容和工具结果不落盘。
• Trace 默认写入 ~/.nano/traces/traces.db；/trace 查看最近记录，/trace <trace_id> 查看事件时间线。Trace 写入必须 fail-open，不能影响 Agent 主流程。
• /eval run <case-id> 复用真实 Agent/ToolRegistry/MCP/HITL 链路；editing/safety 在固定 fixture 临时工作区执行，并由确定性检查和 LLM-as-Judge 联合判定。
• 批量运行必须显式添加 --all；--repeat 1-10 控制重复采样，--fail-under 显示通过率门槛结果，报告默认写入 ~/.nano/eval/。
• 默认 CLI 启动路径应尽早建立 Terminal -> LineReader -> Renderer，启动 Banner、模型加载、MCP 启动、Skill summary、ReAct 提示和退出提示都应走 Renderer.stream()；除 fatal bootstrap / runtime API / legacy TUI 降级外，不要在交互主路径新增裸 System.out.println。
• 启动期 MCP 不得阻塞首屏：CLI 默认最多等待 8 秒（NANO_MCP_STARTUP_WAIT_SECONDS / -Dnano.mcp.startup.wait.seconds 可调），超时后保留未完成 server 为 STARTING 并后台继续初始化；/mcp 查看最新状态。
• LineReader 使用 NanoHighlighter 做输入实时高亮：slash 命令、@ 引用、@image:、@clipboard、敏感词和明显危险 shell 片段会在编辑阶段被标记；不要把这类视觉提示混入最终提交文本。
• LineReader 使用 NanoCompleter 做上下文补全：/model provider、/mcp 子命令与 server、/skill 子命令与 skill name、/task / /browser / /snapshot 子命令、@image: 本地路径、本地 @path 和 MCP resource @server:uri 引用都应从同一个 completer 出口维护。
• 普通用户输入进入 Agent 前会先展开 MCP resource mention，再由 LocalPathMentionExpander 展开本地 @path：文件会内联为 <file> 块，目录会内联为 <directory> 列表；绝对路径或符号链接逃逸项目根时保持原文不展开。
• LineReader 使用 NanoHistory 持久化输入历史到 ~/.nano/history/input.history；如果 nano.history.file / NANO_HISTORY_FILE 指向目录，也会自动使用该目录下的 input.history，避免把目录当文件读；默认忽略空白、重复、明显密钥/Bearer、base64 图片和超长输入，用户可用 /history clear 清空本机输入历史。
• JLine 交互升级计划记录在 docs/phase-22-jline-interaction-upgrade.md。

关键行为约束（Agent 必读）

Memory

• 长期记忆只通过 /save 或用户明确要求保存；不要自动提取事实
• 长期记忆只保存跨会话稳定事实，不保存临时指令
• 长期记忆使用 ~/.nano/memory/long_term_memory.db（SQLite）；首次启动会迁移旧 long_term_memory.json
• 两道压缩不要混淆：shortTermMemory 压缩 vs conversationHistory 压缩（后者是防 window 超限的关键）

HITL + 策略层

• 拦截顺序：HitlToolRegistry → ToolRegistry → PathGuard/CommandGuard
• 用户无法批准策略拒绝的请求
• PathGuard 强制路径限定在项目根内
• CommandGuard 是辅助黑名单，不是主防线

Plan 审阅交互

• Enter 执行 / Ctrl+O 展开 / ESC 取消 / I 补充重规划
• 方向键不应被误判为 ESC
• 涉及改动要连 raw mode 和回退路径一起看

并行工具

• 三条路径都走 executeTools()，不手写 for-loop
• 默认最多 4 个并发，结果保持原始顺序

Web + Browser

• 已知 URL 先 web_fetch，SPA/防爬墙 fallback 到 Chrome DevTools MCP
• 浏览器读取优先 take_snapshot，不默认 take_screenshot
• 公开页面不要提前切 shared 模式

Skill

• system prompt 索引段注入三处提示词，上限 20 个 / 4KB
• load_skill → SkillContextBuffer → 下一轮 user message 前置注入

修改时的硬规则

1. 改行为 → 同步文档

AGENTS.md / README.md / ROADMAP.md（仅状态变化时）

2. 改命令入口 → 联动

Main.java + CliCommandParser.java + 测试 + README.md + AGENTS.md

未识别的 /xxx 在 CLI 层直接报"未知命令"，不回退给 Agent。

3. 改 Plan 审阅交互 → 联动

Main.java + PlanReviewInputParser.java + 测试 + 手工验证

4. 改工具集 → 联动

ToolRegistry.java + Agent/PlanExecuteAgent/SubAgent 提示词 + 可能 Planner 提示词 + 文档

5. 改模型/接口 → 联动

对应 Client + LlmClientFactory.java + .env.example + 文档

5.1 改 Embedding → EmbeddingClient + VectorStore + .env.example + 文档

5.2 改 Web/搜索 → web/ 相关 + ToolRegistry + .env.example + 文档 + 测试

5.3 改 Memory → MemoryManager + LongTermMemory + TokenBudget + 测试 + 文档

5.4 改 HITL/策略 → policy/ + ToolRegistry + HitlToolRegistry + 提示词 + .env.example + 文档 + 测试

5.5 改 MCP → mcp/ + ToolRegistry + HITL + AuditLog + 提示词 + 文档 + 测试

5.6 改 Trace/Eval → trace/ + eval/ + ToolRegistry + Main 命令 + benchmark + 测试 + 文档

6. 不提交 .env / 真实 API Key / target/ 产物

7. 保持代码可读性，不过度抽象

验证路径

给新线程的导航

1. 先看本文件 → 2. README.md → 3. Main.java → 4. 按任务进入对应模块

当前已知边界

以下在路线图但未交付：容器/VM 沙箱 / MCP OAuth + sampling + server 自动重启

不要把 ROADMAP.md 中"将来要做"误读成"现在已有"。

持续维护约定

形成稳定协作规则时直接补进本文件，不要只留在聊天记录里。详细实现细节补到 docs/agents-reference.md。