Skip to content

agents-reference.md

Latest commit

 

History

History
313 lines (228 loc) · 19.6 KB

agents-reference.md

File metadata and controls

313 lines (228 loc) · 19.6 KB

AGENTS Reference: Detailed Feature Behavior

This document contains detailed feature behavior descriptions, configuration reading orders, and implementation notes that were previously in AGENTS.md. Consult this when working on specific modules.

For the primary entry point, see /AGENTS.md.

Configuration Reading Orders

API Key

  1. ~/.navicode/config.json 中对应 provider 的 apiKey
  2. 环境变量：GLM_API_KEY / DEEPSEEK_API_KEY / STEP_API_KEY / KIMI_API_KEY / FREELLMAPI_API_KEY（Kimi 兼容 MOONSHOT_API_KEY）
  3. 仓库当前目录下的 .env
  4. 用户主目录下的 .env

Persistence Locations

数据 默认路径 覆盖方式
长期记忆 ~/.navicode/memory/long_term_memory.json -Dnavicode.memory.dir
工作区记忆 .navicode/memory/MEMORY.md / checkpoint.md / goal.md / notes.md / tasks/<id>/progress.md 跟随项目根目录
RAG 索引 ~/.navicode/rag/codebase.db -Dnavicode.rag.dir
审计日志 ~/.navicode/audit/audit-YYYY-MM-DD.jsonl NAVICODE_AUDIT_DIR / -Dnavicode.audit.dir
Side-Git 快照 ~/.navicode/snapshots/<project_hash>/<worktree_hash>/.git NAVICODE_SNAPSHOT_DIR / -Dnavicode.snapshot.dir
后台任务 ~/.navicode/tasks/tasks.db —

Snapshot Config

系统属性 > 环境变量 > 默认值：navicode.snapshot.enabled(true) / navicode.snapshot.max(50) / navicode.snapshot.excludes(.git,.navicode/snapshots,target,node_modules,dist,.idea,.class,.jar) / navicode.snapshot.dir(~/.navicode/snapshots)

Embedding Config

环境变量 > 系统属性 > 默认值：EMBEDDING_PROVIDER(ollama) / EMBEDDING_MODEL(nomic-embed-text:latest) / EMBEDDING_BASE_URL(http://localhost:11434)

Log Config

系统属性 > 环境变量/.env > 默认值：NAVICODE_LOG_DIR(~/.navicode/logs) / NAVICODE_LOG_LEVEL(INFO) / NAVICODE_LOG_MAX_HISTORY(7) / NAVICODE_LOG_MAX_FILE_SIZE(10MB) / NAVICODE_LOG_TOTAL_SIZE_CAP(100MB)

ReAct/SubAgent Budget Config

系统属性 > 默认值：navicode.react.token.budget(Integer.MAX_VALUE) / navicode.react.stagnation.window(3) / navicode.react.hard.max.iterations(50)

设计取舍：长上下文模型默认不再以 80% x window 为硬限。死循环防护由 stagnation 检测（连续 3 轮相同工具调用）和 hardMaxIterations（50 轮）兜底。Token 显示行 📊 Token: 已用 X / Y 的 Y 是软提示，不代表强制限制。

LLM HTTP Timeout Config

系统属性 > 默认值：navicode.llm.connect.timeout.seconds(60) / navicode.llm.read.timeout.seconds(300) / navicode.llm.write.timeout.seconds(60) / navicode.llm.call.timeout.seconds(600)

SSE 流式下 readTimeout 是两次 read 间最大间隔，GLM-5.1 生成大段 reasoning 时可能长时间静默，所以放宽到 300 秒。

Web Search Provider Config

  1. SEARCH_PROVIDER 显式指定 zhipu / serpapi / searxng
  2. 未指定时按 Key 自动判断：GLM_API_KEY → zhipu / SERPAPI_KEY → serpapi / SEARXNG_URL → searxng
  3. 都没有 → zhipu 占位

各 provider：zhipu(GLM_API_KEY + 可选 ZHIPU_SEARCH_ENGINE) / serpapi(SERPAPI_KEY) / searxng(SEARXNG_URL)

Web Fetch Security (NetworkPolicy)

scheme 白名单(http/https) / 主机黑名单(localhost/loopback/link-local/site-local) / 响应体上限 5MB / 超时 30s / 限流 30次/60s

MCP Config

  1. 用户级：~/.navicode/mcp.json
  2. 项目级：.navicode/mcp.json
  3. 按 server 名 merge，项目级覆盖用户级

格式兼容 Claude Code：command + args = stdio，url + headers = Streamable HTTP。内置变量：${PROJECT_DIR}、${HOME}；其他 ${VAR} 从系统环境变量、系统属性、项目 .env、用户 ~/.env 读取。 检测到 STEP_API_KEY 时自动内置 step_search 远程 MCP（显式同名配置优先），用于 Step 3.7 Flash 的 web_search / web_fetch 优先代理。

Detailed Feature Behavior

ReAct Mode

  • 主入口：Agent.java
  • 退出条件由 LLM 自决（不返回 tool_calls 即结束）
  • AgentBudget 三种兜底：token 超预算 / 连续 3 轮相同调用 / 50 轮硬上限
  • 流式输出 reasoning_content + content；inline ReAct 用固定高度 live thinking 区动态预览 reasoning，同一次输入只把完整 reasoning 引用块落到 transcript 一次；live 区只允许清理自己占用的行，避免覆盖旧输出
  • inline 流式回答用低调 ▪ 标记起始，不再输出强标题；plain / 非流式兜底仍可使用传统 reasoning + answer 文本
  • TerminalMarkdownRenderer 渲染 Markdown 表格时按终端列宽分配列宽，长内容在单元格内部换行；CJK 字符按显示宽度计算，避免表格行被终端自动折断后错位

Long Context Engineering

  • ContextProfile 计算 short/balanced/long 模式
  • GLM-5.1: 200k / DeepSeek V4: 1M / StepFun: 256k / Kimi K2.6: 256k / FreeLLMAPI: 128k
  • long 模式(>=100k)：跳过 Memory 自动摘要，search_code 语义辅助 topK=20，MCP resources 自动索引；精确代码定位仍优先实时 glob/grep/read
  • prompt caching：能力声明 + cached usage 解析

Memory System

  • 默认记忆检索模式为 long_term_only：system prompt 只注入长期稳定事实；当前会话短期上下文通过 conversationHistory 作为 message history 进入模型
  • 实验模式 long_plus_short 可通过 -Dnavicode.memory.retrieval=long_plus_short / NAVICODE_MEMORY_RETRIEVAL=long_plus_short 启用，会额外检索短期摘要/工具摘要，并跳过当前 query 与 active history 已有内容
  • 两道压缩：
    1. ConversationHistoryCompactor 压缩 conversationHistory（真正发给 LLM 的消息，默认启用）
    2. ContextCompressor 只在 long_plus_short 实验模式下压缩 shortTermMemory，用作短期检索摘要来源
  • ConversationHistoryCompactor 切割在 user message 边界，保留最近 3 个 user 起算的尾部
  • 三条路径(ReAct/Plan/SubAgent)都接入 conversationHistory 压缩
  • 长期记忆只通过 /save 或用户明确要求保存
  • 长期记忆只保存跨会话稳定事实，不保存临时指令；默认项目级作用域，跨项目通用偏好才用 global
  • 长期记忆管理命令：/memory list、/memory search <关键词>、/memory delete <id>、/memory clear
  • 工作区记忆文件由 WorkspaceMemory 维护：项目级事实追加到 MEMORY.md，ReAct 正常结束写结构化 checkpoint.md，任务追踪写 tasks/<id>/progress.md；构建 prompt 记忆时会按预算注入这些文件
  • checkpoint.md 固定包含 Current Goal / Completed / In Progress / Blockers / Key Files / Verification Commands / Next Steps / Work Tasks，作为跨会话恢复状态，而不是只保存最后一轮摘要
  • /goal set <目标> 写入 .navicode/memory/goal.md 并同步 checkpoint；/goal 查看状态；/goal clear 清除。存在 active goal 时，ReAct 正常结束会调用 judge LLM 判断 complete / continue / blocked，judge 失败只降级为提示，不阻断原回答
  • /dream 只生成候选 MEMORY.md 建议稿 / diff，扫描 checkpoint、notes 和 task progress；默认不自动写入长期记忆

Multi-Agent

  • 三角色：Planner / Worker(默认 2 个) / Reviewer
  • 流程：规划 → 按依赖分配 Worker → Reviewer 审查 → 未通过重试(最多 2 次)
  • SubAgent IOException 返回 ERROR 类型
  • 所有子代理共享 ToolRegistry 和 MemoryManager

HITL System

  • 危险工具：write_file(中) / execute_command(高) / create_project(中) / revert_turn(高)
  • 审批选项：y(批准) / a(全部放行) / n(拒绝) / s(跳过) / m(修改参数)
  • fail-safe：连续 5 次无效输入判为 REJECTED
  • 并发：requestApproval 整体 synchronized

HITL Enhancement (Policy Layer)

  • PathGuard：路径限定在项目根内（绝对路径外逃 / .. 穿越 / 符号链接逃逸）
  • CommandGuard：fast-fail 黑名单（sudo/rm -rf/mkfs/dd/fork bomb/curl|sh 等）
  • ResourceLimit：write_file 5MB / execute_command 60s + 8KB 输出
  • AuditLog：JSONL 字段 timestamp/tool/args/outcome/reason/approver/durationMs
  • 拦截顺序：HitlToolRegistry → ToolRegistry → 策略层。用户无法批准策略拒绝的请求

Parallel Tool Execution

  • executeTools() 固定线程池并行，默认最多 4 个并发
  • 返回结果保持原始顺序
  • Agent/PlanExecuteAgent/SubAgent 三条路径都走 executeTools()

Web Capabilities

  • web_search：SearchProvider 接口，返回 SearchResult 列表
  • web_fetch：NetworkPolicy → WebFetcher → HtmlExtractor，SPA/防爬墙返回空正文 + 边界提示
  • ReAct freshness preflight：用户输入命中最新/当前/今天/今年/2026/趋势/新闻/版本等时效性关键词且未显式禁止联网时，Agent 在第一轮 LLM 前执行一次内置 web_search，并把结果作为 联网预检结果 注入当前对话。
  • StepSearch 优先级：当前模型 provider=step 且 model 以 step-3.7-flash 开头，并且自动/显式 mcp__step_search__web_search / mcp__step_search__web_fetch 已注册时，内置 web_search / web_fetch 会先代理到 StepSearch MCP；MCP 未就绪或返回不可用结果时回退原实现。
  • JS 渲染 fallback 到 Chrome DevTools MCP

MCP Protocol

  • stdio + Streamable HTTP 双 transport
  • 工具注册为 mcp__{server}__{tool}
  • McpSchemaSanitizer 清洗 inputSchema
  • 所有 mcp__ 工具默认走 HITL + AuditLog
  • resources 双轨：虚拟工具 + @-mention 输入层
  • CLI 首屏默认只等待 MCP 启动 8 秒，慢 server 后台继续初始化并保持 starting，用 /mcp / /mcp logs <name> 追踪
  • notifications 路由：tools/list_changed → 工具全量替换，resources 变化 → cache 失效

Chrome DevTools MCP

  • 默认 server：chrome-devtools，npx -y chrome-devtools-mcp@latest --isolated=true
  • /browser connect：切到 --autoConnect 复用登录态 Chrome
  • /browser connect <port>：旧式 CDP 端口路径
  • /browser disconnect：切回 isolated
  • 敏感页面策略：改写型工具必须单步 HITL，不复用全部放行
  • shared 模式 close_page 只允许关闭 Navicode 创建的 tab

Skill System

  • 三层加载：jar 内置 < 用户级 ~/.navicode/skills/ < 项目级 .navicode/skills/
  • frontmatter：name(必填) / description(必填,<=500) / version / author / tags
  • system prompt 索引段注入到三处提示词末尾，上限 20 个 / 4KB
  • load_skill 工具把 SKILL.md 正文(5KB 截断)写入 SkillContextBuffer
  • buffer 一次性消费，最多 3 个 skill body

TUI (v16.1 Renderer Architecture)

  • 三个实现：InlineRenderer(默认) / LanternaRenderer / PlainRenderer
  • 环境变量：NAVICODE_RENDERER=inline|lanterna|plain
  • NAVICODE_TUI=true(旧) → lanterna + deprecation 提示
  • NAVICODE_NO_STATUSBAR=true：禁用底部状态栏
  • NO_COLOR=1：禁用 ANSI 颜色
  • 当前开屏 Banner 是无右侧盒线边框的简洁布局，避免 ANSI/CJK 字宽导致竖线错位
  • InlineRenderer 复用 JLine 4 的编辑能力，默认提示符是 * ，右提示显示 message / @path / @image
  • BottomStatusBar 是 JLine Status 托管的底部 dock：由 JLine 负责滚动区域和状态行位置，不再手写 \n、moveUp、CLEAR_TO_EOS 或绝对光标行号；dock 上层展示 YOLO/HITL 与 MCP/Skill 摘要，下层展示 model、phase、ctx、token、cost、elapsed 与 cwd。ctx 只表示当前仍会带入下一轮请求的上下文估算，in/out/cache 表示最近任务调用统计。
  • /clear 清空当前 ReAct conversationHistory、shortTermMemory 和待注入 SkillContextBuffer，并重建不含上一轮检索记忆的 system prompt；长期记忆条目保留，后续只会按新查询重新检索注入。
  • 普通任务和斜杠命令提交后都会以 > 暗色整行块回写原始输入，避免 JLine accept 后清掉编辑行导致结果区看不到刚执行的命令
  • InlineRenderer 不使用独立 JLine Display.update() 维护 thinking 临时区；真实终端验证发现独立 Display 会在 transcript/status 输出后从错误位置向上清屏。当前实现用固定高度 live 区重写自身行，content/tool 边界先清理 live 区再追加 transcript。
  • 交互期输出优先走 Renderer.stream()；Main、PlanExecuteAgent、Planner、AgentOrchestrator 都可接收同一个 renderer 输出流，避免绕过 inline renderer 直接写 stdout
  • CodeIndex 通过 ProgressListener 上报索引开始 / 文件数量 / 进度 / 完成或失败，/index 绑定当前 renderer 输出流；内部异常细节写 logger

LSP Diagnostics (Phase 17)

  • write_file 成功后对 Java 文件做 JavaParser 语法诊断
  • 诊断作为合成 user message 注入下一轮 LLM 请求
  • NAVICODE_LSP_ENABLED=false 关闭

Git Side-History Snapshot (Phase 18)

  • side-git 在 ~/.navicode/snapshots/ 维护独立仓库（JGit，不依赖系统 git）
  • pre-turn 同步，post-turn 异步
  • revert_turn 纳入 HITL/AuditLog，恢复前先创建 pre-restore 快照

Prompt Layering (Phase 19)

  • 组装顺序：base → personality → mode → approval → runtime_context → project_context → skills → context_mgmt → handoff
  • runtime_context 每轮注入当前日期和系统时区，供最新信息、相对日期和联网决策使用
  • 覆盖优先级：jar 内置 < 用户级 ~/.navicode/prompts/ < 项目级 .navicode/prompts/
  • 必要校验：base.md 和最终 prompt 必须包含 ## Language

Async Tasks + Runtime API (Phase 20)

  • DurableTaskManager(SQLite) / 后台队列 CLI: /task, /task list, /task add, /task cancel, /task log
  • 工作任务 CLI: /task new <摘要>, /task sub <parent_id> <摘要>, /task board [--all], /task start|block|done|abandon <id> [说明], /task gate
  • 未完成任务闸门只提示 open / in_progress；blocked 代表真实阻塞，不强制 re-entry
  • 工作任务创建和 start/block/done/abandon 状态变化会刷新结构化 checkpoint 的 Work Tasks 区域；stopGateReminder 语义保持不变
  • Runtime API: serve --http --port 8080，仅 127.0.0.1，需 API Key
  • 端点：POST /v1/threads / POST /v1/threads/{id}/turns / GET /v1/threads/{id}/events

Image Input (Phase 21)

  • LlmClient.ContentPart 支持 text / image_base64 / image_url；纯文本仍序列化为 string content，图片消息序列化为 OpenAI-compatible content array
  • ImageProcessor 统一处理本地 @image:、@clipboard 和 MCP image content：透明图铺白底，超限图缩放 / 压缩到 5MB base64 API 上限内，不做 OCR
  • 输入：@image:file:///path.png / @image:/path.png / @image:relative.png / @image:<file:///path with spaces.png> / @clipboard；Ctrl+V 会把剪贴板图片保存到 ~/.navicode/cache/ 并注入 @image:<path>
  • CLI 输入层不按模型名拦截图片；GLM-5V-Turbo 可通过 /model glm-5v-turbo 切换，其他 provider 是否接受图片以 API 返回为准
  • ReAct / Plan task executor / SubAgent 都会把用户图片和 MCP imageParts 作为 user image message 送入模型；tool message 保留文本 fallback
  • 历史 image payload 会在下一轮前替换为文本占位，保留 Image source 等元信息，避免旧截图反复消耗上下文或污染新图分析

Core File Descriptions

Main.java

CLI 入口 / Banner / .env 读取 / 日志初始化 / 模式切换 / JLine raw mode

Agent.java

ReAct 主循环 / 对话历史 / 工具调用与结果回灌

PlanExecuteAgent.java

规划后执行 / 计划审阅 / DAG 任务执行 / 并行批次 / 失败重规划

AgentOrchestrator.java

Multi-Agent 编排器 / 三角色管理 / 按依赖分配 / 审查重试

SubAgent.java

可配置角色子代理 / 独立对话历史 / Worker 用工具、Planner/Reviewer 不用

Planner.java

LLM 生成计划 JSON / 简单任务最小计划 / 重编号 task_1..N / 依赖计算

ExecutionPlan.java

DAG 拓扑排序 / 可执行任务判定 / 进度可视化

ToolRegistry.java

11 个核心内置工具 + MCP 动态工具 / executeTools() 并行入口 / ToolInvocation / ToolExecutionResult。代码理解默认路径是 glob_files / grep_code / read_file 现用现查，grep_code 优先走 ripgrep 并按 max_results / head_limit / max_chars 渐进返回，search_code 保留为 RAG 语义辅助。确定性搜索链路的回归样例见 docs/code-search-golden-set.md。

MCP Package

McpServerManager / McpClient / JsonRpcClient / StdioTransport / StreamableHttpTransport / McpSchemaSanitizer / resources/ / mention/ / notifications/

TUI Package

TuiBootstrap / LanternaWindow / TuiSessionController / pane/ / hitl/ / history/ / highlight/

LLM Clients

  • GLMClient：glm-5.1，glm-5v 开头切多模态接口
  • DeepSeekClient：deepseek-v4-flash，thinking + tool calls 带回 reasoning_content
  • StepClient：step-3.5-flash，可通过 STEP_BASE_URL 切通道
  • KimiClient：kimi-k2.6，thinking + tool calls 带回 reasoning_content
  • FreeLlmApiClient：auto，默认 http://localhost:5173/v1，OpenAI-compatible 本地网关；可用 /config provider freellmapi ... 写入配置后 /model freellmapi 切换

.env.example Reference

GLM_API_KEY=your_api_key_here
# GLM_MODEL=glm-5.1
# GLM_MODEL=glm-5v-turbo
# DEEPSEEK_API_KEY=your_deepseek_api_key_here
# DEEPSEEK_MODEL=deepseek-v4-flash
# STEP_API_KEY=your_step_api_key_here
# STEP_MODEL=step-3.5-flash
# STEP_BASE_URL=https://api.stepfun.com/v1
# KIMI_API_KEY=your_kimi_api_key_here
# MOONSHOT_API_KEY=your_moonshot_api_key_here
# KIMI_MODEL=kimi-k2.6
# KIMI_BASE_URL=https://api.moonshot.ai/v1
# FREELLMAPI_API_KEY=your_freellmapi_unified_key_here
# FREELLMAPI_MODEL=auto
# FREELLMAPI_BASE_URL=http://localhost:5173/v1
EMBEDDING_PROVIDER=ollama
EMBEDDING_MODEL=nomic-embed-text:latest
EMBEDDING_BASE_URL=http://localhost:11434
# EMBEDDING_API_KEY=your_api_key_here
# NAVICODE_LOG_LEVEL=INFO
# NAVICODE_LOG_DIR=/Users/yourname/.navicode/logs
# NAVICODE_LOG_MAX_HISTORY=7
# NAVICODE_LOG_MAX_FILE_SIZE=10MB
# NAVICODE_LOG_TOTAL_SIZE_CAP=100MB
# NAVICODE_SNAPSHOT_ENABLED=true
# NAVICODE_SNAPSHOT_MAX=50
# NAVICODE_SNAPSHOT_EXCLUDES=.git,.navicode/snapshots,target,node_modules,dist,.idea,*.class,*.jar
# NAVICODE_SNAPSHOT_DIR=/Users/yourname/.navicode/snapshots
# NAVICODE_TUI=true
# NO_TUI=true

Test Coverage Summary

测试覆盖偏向：解析、计划结构、RAG 核心、Multi-Agent 编排、HITL 策略、策略层拦截、MCP 协议、资源输入层、长上下文策略与 Skill 加载。

不覆盖：真实 LLM 联调、真实 Embedding API、真实 MCP server 联调、终端完整手工体验。

完整测试类列表：CliCommandParserTest / MainBrowserCommandTest / PlanReviewInputParserTest / MainInputNormalizationTest / ExecutionPlanTest / MemoryEntryTest / ConversationMemoryTest / LongTermMemoryTest / MemoryRetrieverTest / MemoryManagerTest / ExplicitMemoryHintsTest / ContextProfileTest / PlanExecuteAgentTest / AgentMemoryHintTest / AgentRoleTest / AgentMessageTest / AgentOrchestratorTest / EmbeddingClientTest / SearchResultTest / NetworkPolicyTest / HtmlExtractorTest / WebFetcherTest / SearchProviderFactoryTest / ZhipuSearchProviderTest / VectorStoreTest / CodeChunkerTest / CodeAnalyzerTest / CodeIndexTest / ApprovalPolicyTest / ApprovalResultTest / HitlToolRegistryTest / TerminalHitlHandlerTest / ToolRegistryTest / BrowserSessionTest / BrowserConnectivityCheckTest / SensitivePagePolicyTest / BrowserGuardTest / McpSchemaSanitizerTest / McpConfigLoaderTest / JsonRpcClientTest / McpToolBridgeTest / McpResourceCacheTest / AtMentionParserTest / AtMentionExpanderTest / AtMentionCompleterTest / NotificationRouterTest / PathGuardTest / CommandGuardTest / AuditLogTest / SkillFrontmatterParserTest / SkillRegistryTest / SkillStateStoreTest / SkillBuiltinExtractorTest / SkillContextBufferTest / SkillIndexFormatterTest / LoadSkillToolTest / SkillCommandHandlerTest