AI Research 技术调研

Augment Code (Auggie CLI / Cosmos)：闭源 npm 分发的 coding agent，核心逻辑靠 12MB 未混淆 JS bundle 逆向 + 官方 docs/blog 拼出的源码级 dossier

36分钟阅读

Augment Code (Auggie / Cosmos)

一句话定位

Augment Code 的 coding agent 以闭源 npm 包 @augmentcode/auggie（当前锚定版本 0.32.0）分发，GitHub 上的 augmentcode/auggie 仓库是公开的但只是插件市场 + 示例命令（100% Shell），不含任何真实 harness 逻辑；真正的实现是一个 ~12MB、8173 行、变量名混淆但字符串字面量（含全部 prompt 文本）未混淆的单文件 bundle augment.mjs，本 dossier 的源码级论断全部来自对该 bundle 的 grep/子串提取，辅以 docs.augmentcode.com（经其 llms.txt 索引抓取 17 篇一手文档）和两篇官方博客（成本质量对比、Prism 模型路由）。Augment 的技术定位是”Context Engine + 模型无关”，最有实质内容的自曝技术细节是模型路由器 Prism（缓存感知的分轮路由，服务端实现，客户端无代码）和五个内建 subagent 的完整 verbatim 提示词。CLI 内部代号 “Beachhead”。

核心架构总览（目录结构关键路径 + 引用的 commit）

  • 锚定版本：npm 包 @augmentcode/auggie@0.32.0，tarball shasum 70e0311f6ed8303520a912d485aa788de94fb9db，2026-07-07 通过 npm pack @augmentcode/auggie@0.32.0 拉取解包。存在更新的 prerelease dist-tag 0.33.0-prerelease.3，未分析。
  • 包内容（相对 package/）：augment.mjs（~12MB，8173 行，minified 但字符串字面量完整存活——包括系统提示词、工具名、配置 key 全部可 grep 到）、README.md、LICENSE.md、package.json（engines 声明 Node ≥20，但 GitHub README 写 Node 22+，两处不一致，如实记录）。bin: auggie -> augment.mjs。Bundle 头部内嵌 Sentry debug ID 80d4e217-3600-5b6f-af62-f9e588b66d22。
  • GitHub 仓库 augmentcode/auggie（公开，249 stars/32 forks/294 tags，最新 tag v0.28.0 落后于 npm）——语言统计 100% Shell，实际内容是 .augment-plugin/、.augment/commands/（示例 slash command）、plugin_marketplace/、.github/。这是默认插件市场，不是 harness 源码，已核实。
  • 内部代号 “Beachhead”：bundle 中大量 Beachhead* 标识符（BeachheadClientWorkspaces、BeachheadPluginFileStore、BeachheadRemoteInfo）与同前缀 feature flag（beachheadEnableParallelToolExecution、beachheadEnableSubAgentTool、beachheadEnableSentry 等）指向 CLI/headless-agent 代码路径的内部代号；bot-type 常量 POSEIDON_CLI_AGENT 与 CLI_AGENT/CLI_NONINTERACTIVE 并列出现，作为内部 agent-mode 标识。
  • Cosmos（Augment 的 SDLC 自动化平台，Workers/Subagents/Expert-to-Expert）与 Auggie CLI 共享部分底层子代理概念，但 Cosmos 层的具体实现（VM 隔离技术等）大部分未披露，仅有产品级设计文档。

Agent Loop（主循环 / 何时继续何时停）

  • 循环终止枚举确认（augment.mjs，grep 命中 Interrupted:"interrupted"）：{Interrupted:"interrupted", EndTurn:"end_turn", MaxIterations:"max_iterations", EmptyCompletion:"empty_completion", Error:"error"}。同一枚举作为 agent_stop_cause 字段出现在公开的 Stop hook 事件文档中（docs/03_hooks.md）。
  • 循环是回合制的：每个用户/工具结果回合触发一次 apiServer.chatStream（服务端往返调用）；回合内的工具调用被解析执行后，循环依据上述 stop cause 判断是否继续。存在 client 侧与（按 agent_max_iterations feature flag）server 侧共同配置的最大迭代守卫（bundle 片段：e.feature_flags.agent_max_iterations!==void 0&&(i.agentMaxIterations=e.feature_flags...)）。
  • 子代理有独立的子循环 subAgentLoop.run（同时也是一个 OTel span 名，与 apiServer.chatStream、toolsModel.callTool、reportAgentStatus、reportChatHistory 并列于 span 白名单集合 Kbo=new Set([...])）。子代理循环由常量 BSt 限制最大回合数，且仅在 _e==="end_turn"||_e==="empty_completion" 且未被中止时继续。
  • 并行工具执行与并行子代理执行都是一等公民：bundle 字符串 "before parallel sub-agent execution"、"before parallel tool execution"、"after parallel tool execution (interrupted)" 是循环内部的中断检查点标签，即同一回合可并发触发多个工具调用/多个子代理，中断检查发生在每个并行批次边界；由 feature flag beachheadEnableParallelToolExecution 控制。
  • CLI 层面的用户控制：auggie --print --max-turns 10 "..." 限制非交互模式下的回合数（docs/08_reference.md）；--dont-save-session、--continue/-c、--resume/-r 控制会话级续接。交互（完整 TUI 流式）/ --print（一次性，CI 用）/ --print --quiet（仅打印最终消息，结构化输出场景）三种运行模式。

记忆与上下文管理（压缩、长期记忆、会话持久化）

  • 本地会话持久化：.augment/sessions/<session_id>.json。Bundle 中一个内部工具描述字符串（loadSessionHistory 邻域 grep 命中）披露了一个三级详略度会话检视工具：“以详略度 1 通读全会话……用详略度 2 深入五个最有意思的回合，用详略度 3 深入单个最重要的回合”——支持/调试向工具，不确定是否面向终端用户。公开 CLI 层：auggie session list[--json|--all|-n <N>]、session continue、session resume [id]、session delete[--all]、session share [id]（docs/08_reference.md）。--dont-save-session 可完全关闭持久化。
  • 长期/跨会话记忆工具：独立内建工具 conversation-retrieval，与 codebase-retrieval/codebase-retrieval-raw 并列于同一工具集合（bundle: Set(["codebase-retrieval","codebase-retrieval-raw","conversation-retrieval","finish-subagent-context-gathering"])，调度分支 case"conversation-retrieval":return wLo(e)）。类名 ConversationRetrievalTool/ConversationRetrievalUtils，配置开关 enableConversationRetrieval。这是对历史会话（不只是当前会话）做语义检索的机制，与代码库 RAG 是分离的两套系统。
  • 详细的上下文预算记账对象（bundle 结构体字段）：modelName, maxContextTokens, totalUsedTokens, systemPromptTokens, chatHistoryTokens, currentMessageTokens, toolResultTokens, assistantResponseTokens, systemToolTokens, mcpToolTokens, systemToolBreakdown, mcpToolBreakdown, toolDefinitionsTokens, freeSpaceTokens, usagePercentage——大概率是某个 /context 用量检视 UI 的后端数据结构。
  • 截断/压缩机制（bundle 对 Truncat 词根的 grep，约 40 个相关标识符）：ToolOutputTruncator 类；UntruncatedContentManager/_untruncatedContentManager 保留截断前内容的影子副本；专用恢复工具 search-untruncated、view-range-untruncated（通过 pushUntruncatedRecoveryTools 注册）；telemetry 中上报 codebase_truncated、conversation_truncated、final_truncated 等分类截断标记，及 conversation_budget、codebase_budget、total_budget 预算字段。即：工具输出/检索结果按显式 token 预算截断，但原始未截断内容被缓存，可通过 -untruncated 变体工具重新取回，而非直接丢弃。
  • Prism 的缓存感知路由也是记忆/成本相关的设计决策（详见 Router 章节）：跨模型切换会以约 10 倍代价驱逐 prompt cache，因此 Prism 刻意避免回合内切换，将路由决策摊销到整个回合的工具调用后续中。
  • 代码库上下文（工作区索引）：.gitignore + .augmentignore（支持 ! 前缀强制纳入被 gitignore 排除的路径，如 node_modules）控制 Context Engine 索引范围（docs/10_workspace-indexing.md）。首次进入项目目录自动触发索引；--allow-indexing 跳过确认提示，--wait-for-indexing 阻塞直到索引完成后再执行首个 codebase-retrieval。Context Engine 具体的分块/嵌入方式未公开披露（仅有 Context Connectors 这个更通用的开源相关管线文档，与核心专有 Context Engine 是两回事）。

工具体系（定义/调用协议/注册/权限）

  • 权限系统是完整文档化的策略 DSL（docs/02_permissions.md）：settings.json（~/.augment/settings.json 用户级，或 workspace .augment/settings.json/.augment/settings.local.json）中的规则数组，每条规则 {toolName, permission:{type: allow|deny|ask-user|webhook-policy|script-policy}, shellInputRegex?, eventType?}，first-match-wins、自上而下评估。eventType 可为 tool-call（执行前拦截，默认）或 tool-response（执行后，可注入反馈但不能阻断）。ask-user 在非交互/--print 模式下自动拒绝。webhook-policy 把 JSON payload（tool-name, event-type, details, timestamp）POST 到外部 URL，期望回传 {allow, output?}；script-policy 通过 stdin 管道给本地脚本，用退出码判定（0=allow，非 0=deny）。
  • Bundle 内确认服务端/客户端双侧执行：标识符 ToolPermissions、convertToolPermissionRule、getToolPermissionRules、setToolPermissionRules，以及租户级变体 getTenantToolPermissionRules、enableTenantLevelToolPermissions——即除用户级设置外还存在组织/租户级策略覆盖层，与 docs/03_hooks.md 中记载的 /etc/augment/settings.json”不可变、管理员控制”层一致。
  • 规范内建工具名（docs/02_permissions.md + bundle grep）：进程类 launch-process, read-process, write-process, list-processes, kill-process；文件类 view, str-replace-editor, save-file, remove-files, codebase-retrieval, grep-search；外部集成类 github-api, linear, notion, supabase, web-search, web-fetch。Bundle 额外揭示文档未收录的内部工具名：codebase-retrieval-raw、conversation-retrieval、finish-subagent-context-gathering、finish-subagent-task、apply_patch、find-tool、execute-tool、search-untruncated、view-range-untruncated。
  • MCP 工具命名为 {tool-name}_{server-name}，截断至 64 字符，权限系统一视同仁（支持 mcp:*/mcp:.*_my-server$ 匹配模式）。
  • MCP 工具搜索/惰性暴露模式：--enable-tool-search 隐藏各个 MCP 工具，只暴露两个元工具 find-tool/execute-tool（docs 与 bundle 双重确认：DWe="find-tool",GWe="execute-tool"，带 JSON-schema 字符串 {"type":"object","properties":{"query":{"type":"string","description":"Detailed descriptio[n...]）——直接针对”注册过多 MCP server/工具导致上下文膨胀”的缓解机制；mcpTotalToolsCount 被追踪并可通过 includeMCPMetadata 暴露给 hooks。
  • 工具 schema 可自省：auggie tools schemas 打印工具定义+输入 JSON-Schema；auggie tools list/add/remove 管理持久化的 removedTools 列表；--remove-tool <name> 为单次运行覆盖（docs/08_reference.md）。
  • MCP server 管理：auggie mcp add/add-json/list/remove，settings.json 下 mcpServers 配置 http/sse/stdio 三种传输方式，支持 ${workspaceFolder} 变量展开（docs/12_integrations.md）。Bundle 确认健壮的 server 生命周期处理：McpServerManager、_handleMcpServerWedged（检测并恢复卡死的 MCP server）、handleRestartMcpServer、addEphemeralMcpServer vs addPersistentMcpServers。
  • 通过 launch-process 启动的任意进程会被设置环境变量 AUGMENT_AGENT=1，供脚本探测自己在 agent 控制下运行（docs/08_reference.md）。

Prompt 设计（系统提示结构、动态组装）

  • 顶层/编排器系统提示词完全不在客户端 bundle 中 —— 对 "You are Augment"、"You are an AI coding agent"、"You are a coding agent"、"agentic coding assistant"、"You are Auggie" 等字符串的穷举 grep 均零命中。结合 chatStream(...) 调用签名接收 systemPrompt、systemPromptAppend、systemPromptReplacements 作为传给 API 的参数（bundle 片段：...parallelTools:N,conversationId:V,signal:k,systemPrompt:L,systemPromptAppend:z,systemPromptReplacements:G,...），强烈提示基础/编排器系统提示词是服务端组装的，客户端只提供片段/覆盖项——这是从代码结构推断，非直接自曝披露，明确标注为推断而非事实。
  • 相对地，五个内建 subagent 提示词完全在客户端、逐字可提取（已完整存档于 extracted-from-npm-bundle/subagent-prompts.md）：research、plan、code、validate（通用角色提示词，各带工作流+明确输出格式模板）与 context-gathering（篇幅更长、高度定制，见 Router/自进化章节）。这些 subagent 支持 replaceSystemPrompt、disableRules、disableWorkspaceGuidelines、disableSkills 标志——即框架支持对基础系统提示词整体替换或叠加；context-gathering 的配置为 replaceSystemPrompt:!1,disableRules:!0,disableWorkspaceGuidelines:!0,disableSkills:!0（保留基础提示词结构但剥离 rules/workspace guidelines/skills 注入，即”干净”运行、不带用户项目定制噪音）。
  • 动态 prompt 组装的输入源：Rules（CLAUDE.md/AGENTS.md/.augment-guidelines/.augment/rules/*.md，按目录层级发现，docs/09_rules.md）、Skills（SKILL.md frontmatter+body，按 agentskills.io 规范注入，docs/06_skills.md）、自定义命令（原始 markdown prompt body，frontmatter 带 description/argument-hint/model，docs/07_custom-commands.md）、workspace guidelines——均在请求时叠加到（服务端组装的）基础提示词上。SubAgentConfigLoader（bundle: Odi=Le("SubAgentConfigLoader")）解析 subagent frontmatter key：NAME/DESCRIPTION/MODEL/COLOR/TOOLS/DISABLED_TOOLS/FINISH_TOOL/PROVIDER_MODEL/PROVIDER_API_KEY/PROVIDER_BASE_URL/REPLACE_SYSTEM_PROMPT/DISABLE_RULES/DISABLE_WORKSPACE_GUIDELINES/DISABLE_SKILLS/TOOL_DESCRIPTION/INSTRUCTION_DESCRIPTION——一套丰富的、用户可通过 subagent markdown 文件自主配置的 prompt 组装参数。
  • Rule 的 “type” 语义（always_apply vs agent_requested vs IDE-only manual）构成一层轻量的相关性门控：agent_requested 规则只有当 agent 依据其 description 判断相关时才被拉入上下文，避免未用规则占用上下文。

Router / 编排（任务分解、多 agent、子 agent）

这是本次调研信息量最大的维度，覆盖三个层级：(a) CLI 用户自定义 subagent，(b) CLI 内建命名 subagent，(c) Cosmos 平台级 Workers/Subagents/Expert-to-Expert。

  • (a) 用户自定义 subagent（docs/05_subagents.md）：markdown 文件 + YAML frontmatter（name, description, color, model, tools|disabled_tools），位于 ~/.augment/agents/（用户级）或 ./.augment/agents/（workspace 级，可随 VCS 共享）。拥有独立上下文窗口、独立提示词，与主 agent 及彼此并行运行；工具白/黑名单互斥（同给则黑名单优先）。可通过 /agents 向导交互创建或手写；主 agent 会自动判断任务是否适合已注册的 subagent 并主动调用/建议调用。
  • (b) 内建命名 subagent（bundle v6({name:...}) 注册调用；完整提示词已存档于 extracted-from-npm-bundle/subagent-prompts.md）：
    • research — 模型 claude-haiku-4-5，禁用工具 str-replace-editor, apply_patch, save-file, remove-files, launch-process（只读），颜色 purple。
    • plan — 无显式模型覆盖（继承默认），禁用工具集同上但去掉 apply_patch，颜色 green。
    • code — 仅禁用 launch-process, remove-files，颜色 blue（可写/编辑文件，不能跑 shell 或删文件）。
    • validate — 模型 claude-sonnet-4-6，禁用 save-file, remove-files（可运行测试 launch-process、编辑既有文件，但不能新建/删除文件）。
    • context-gathering — 模型 gemini-3-1-flash-lite-preview（明确区别于 Claude 系列的更便宜模型，是对最高频、最可并行子任务的刻意模型分级），hidden:!0（不对用户直接可见/可选，是某个”派生研究子代理”元工具的内部实现细节），限定恰好 3 个工具：codebase-retrieval-raw, view, grep-search，replaceSystemPrompt:!1, disableRules:!0, disableWorkspaceGuidelines:!0, disableSkills:!0。
    • context-gathering 的提示词篇幅长、细节丰富，值得摘录：明确写出成本不对称性理由——“编排器每 token 的成本大约是你的 20 倍；你跳过的每一次搜索，都会变成编排器不得不用高得多的成本重新做一次的搜索”；对零命中 grep 有明确的反假阴性协议（结论”不存在”前必须以 3 种方式扩大搜索范围）；结构化 finish-tool 契约（summary、scope{searched,notSearched,rationale}、references[]、negativeFindings[{claim,checked,confidence}]、openQuestions[]）。
    • 存在两个不同的”finish”工具：finish-subagent-task（供 code/validate 等执行型 subagent）vs finish-subagent-context-gathering（供只读研究角色），报告契约不同。
  • (c) Cosmos 层级委派（docs/17_workers-subagents.md）——三种刻意分开的机制：
    • Worker = 完整独立的 Cosmos Expert 会话（自带 VM/Environment/集成/权限），重量级，需显式提示才会启动（非自动），作用域为 org 或 Space。
    • Subagent（Cosmos 层）= 轻量、同仓库作用域、无独立 Expert 配置，agent 自主决定是否使用（对应上文 CLI subagent 概念）。
    • Expert-to-Expert = 通过共享集成间接协作（如 PR Author 开 PR，Deep Reviewer 响应 pull-request-created 事件评论，PR Author 再响应新评论）——无直接启动关系，协作面对人类可见（PR 本身）。
    • 官方给出的设计理由原文：“one very broad Expert could try to do every task… in practice, specialized Experts produce better results because the system prompt sets what the agent pays attention to”，并建议”当整个工作流能塞进一个上下文窗口时优先用单个 Expert”，只在必要时才做分解，因为多 agent 协作有和多线程一样的失败模式（竞态、死锁、归属不清）——一段颇为坦率的”何时不该拆分”工程判断。
  • 模型跨回合路由（Prism）——本维度最突出的发现，来自 blog-prism-model-routing.md（官方一手、含具体方法论）：
    • Prism 是一个在每个用户回合前运行的规划器模型，从固定模型池中挑选本回合实际执行的模型。两套已上线配置：Prism (Claude+Gemini) 在 {Opus 4.7, Sonnet 4.6, Gemini Flash 3.0} 间路由，调优目标是匹配 Opus 4.7 质量；Prism (GPT+Kimi) 在 {GPT 5.5, GPT 5.4, Kimi K2.6} 间路由，目标匹配 GPT 5.5 质量。
    • 缓存感知路由是核心工程约束：回合内切换模型会驱逐 prompt cache，使下一回合成本约增加 10 倍。Prism 的策略原文：“switch only when the expected win from a different model exceeds the cost of the cache eviction”——路由决策在一个回合的工具调用后续中保持粘性（不逐工具调用重新评估），且规划器不会打断进行中的回合。
    • 量化开销（官方 blog、生产 telemetry）：规划器成本约为总花费的 0.03%（某 benchmark 跑批中 $2,649 里的 $0.91）；规划器延迟 p50 2.6s / p90 4.0s / p99 5.4s；规划器仅在约 4% 的 chat-host 回合中触发（96% 是复用已缓存路由决策的工具结果后续回合）；跨所有回合规划器约占总请求耗时的 3%；在确实触发的回合中，规划器延迟占用户感知响应延迟的 30-40%（短交互回合场景）。
    • 官方明确列出的近期未实现缺口：无面向用户的”本回合实际用了哪个模型”展示；无法约束/排除路由池中的特定模型；尚无”偏好便宜”vs”偏好最佳”的用户可调旋钮。
    • npm bundle 中未找到 Prism 的客户端代码——对 augment.mjs grep Prism 仅命中无关的 Prisma/语法高亮库 prism 噪声，确认 Prism 规划器逻辑完全在服务端（与”系统提示词服务端组装”的发现一致）。
    • 需注意官方博客自身的表述边界：约 30% 的 cache-read/output-token 相对 Claude Code 的降低，被 Augment 归因于”Context Engine 与我们的 harness”共同作用——即官方口径把检索质量（更少无效探索回合）与 harness 层效率（更少高成本回合）混在一起披露，未清晰拆分归因；原始 token 对比表（来自 Harbor 框架跑分）本身是具体测量数字，但”harness 具体哪部分贡献了多少”应视为营销框架化表述，而非独立验证的拆解。

Skill / 插件体系

  • Skills 严格遵循第三方 agentskills.io 规范（非 Augment 自创格式）：SKILL.md + YAML frontmatter name（1-64 字符、kebab-case、须与目录名一致）+ description（1-1024 字符），body 为自由 markdown 指令（docs/06_skills.md）。发现路径优先级：~/.augment/skills/ > <workspace>/.augment/skills/ > ~/.claude/skills/ > <workspace>/.claude/skills/ > ~/.agents/skills/ > <workspace>/.agents/skills/——显式兼容 Claude Code 的 skill 目录布局及通用 .agents/ 约定。每个被发现的 skill 自动注册为 /<skill-name> slash command（同名内建命令优先）。/skills 弹窗显示 name/source/description/预估 token 数——skill 成本在调用前即对用户可见。
  • 自定义 slash command 是独立的更简单机制：.augment/commands/<name>.md 下的裸 markdown 文件（无强制 frontmatter，亦兼容 .claude/commands/），可选 frontmatter（description、argument-hint、model 覆盖），支持子目录命名空间（frontend/component.md → /frontend:component）与 $ARGUMENTS 风格位置参数；可从 shell 直接执行：auggie command <name>、auggie command list。
  • 插件与市场：auggie plugin marketplace add <github-repo>/list/update/remove；auggie plugin list、auggie plugin install <id>[--disable]；--plugin-dir <path> 用于本地开发。功能受账号 feature flag 门控。augmentcode/auggie GitHub 仓库本身托管 plugin_marketplace/ 目录和 .augment-plugin manifest——该仓库的真实用途是默认插件市场 + 示例命令，已在架构总览一节确认。
  • Skills / Rules / Custom commands 在文档中被明确区分：Skills = 可发现/模块化领域包（agentskills.io 标准）；Rules = 常驻或自动附加的项目约定（Augment 自有格式，markdown，分层 AGENTS.md/CLAUDE.md）；Custom commands = 手动调用的可复用提示词模板。

自进化能力（自我改进 / 学习型记忆 / eval 驱动纠错）

  • 未发现在线自我改进或基于使用数据微调的证据——文档和 bundle 均未披露任何 trajectory-上训练、RLHF 式反馈闭环。
  • 找到的最接近的类比是单次会话内的过程级自我纠错，而非跨会话学习：
    • context-gathering subagent 提示词（见 Router 章节）编码了明确的自我验证协议：“Verify, do not assume”——任何声称的文件路径/符号/行为都必须先用 view 实际打开确认才能报告；否定性结论（“X 不存在”）需要提供已尝试的扩大搜索范围的 checked 清单，专门用于防止过早/错误的否定结论。这是提示词工程出的严谨性，不是学习型/自适应机制。
    • Cosmos 的 Verifier Expert（docs/index via llms.txt，页面本次未完整抓取——cosmos/experts-verifier.md）简介中描述为在真实环境中运行变更并报告”evidence-backed findings”——是 SDLC 自动化产品中的 eval 式验证步骤，但属于配置好的流水线阶段，不是自我修改的 agent。
    • Cosmos 的 Risk Analyzer 与共享**“review memory”（cosmos/experts-code-review.md 简介提到”PR Author, Risk Analyzer, Deep Reviewer, Pair Reviewer, Verifier, and shared review memory”）暗示评审流水线阶段间存在持久化共享记忆，但该页本次未完整抓取，标记为 stage-2 遗留跟进项，未经核实**。
  • 结论：基本未实现 / 官方未公开披露。 Augment 的公开叙事（Prism blog、成本质量 blog）聚焦于路由/检索效率，而非 agent 从历史运行中学习或自我改进。此处如实记录为”未找到”，不做推测性补全。

可观测性（日志 / trace 格式）

  • 完整的 OpenTelemetry 客户端埋点：bundle 内含 @opentelemetry/api、@opentelemetry/instrumentation 及各库自动埋点（amqplib、connect、express、generic-pool、graphql、hapi 等标准 OTel contrib 集合，在 CLI 场景下大概率多数处于未激活状态，但作为共享 SDK 依赖存在）。
  • Sentry 错误追踪已打包并接入 OTel 管线：SentryContextManager、SentryPropagator、SentrySampler、SentrySpanProcessor、SentryMetricsExporter、SentryCallbackHandler，及内部错误类 SentryBufferFullError、SentryDoNotSendEventError、SentryInternalError。由 beachheadEnableSentry/beachheadErrorSamplingRate/beachheadTraceSamplingRate feature flag 控制——即 Sentry/OTel 遥测默认（按采样率）开启，可按租户/flag 关闭，意味着默认情况下 Augment 会采集客户端错误与 trace 遥测。
  • Bundle 中确认的具名 OTel span（来自 Kbo=new Set([...]) span 白名单及相关代码）：apiServer.chatStream、toolsModel.callTool、reportAgentStatus、reportChatHistory、subAgentLoop.run；另有 currentTurnSpan/currentThinkingSpan 对象引用，span event 如 max_iterations_exceeded 携带属性 agent.max_iterations_exceeded。
  • 本地诊断（docs/08_reference.md）：--log-file <path>（默认临时文件，- 输出到 stderr；--mcp/--acp 模式下因 stdio 被协议占用而抑制）、--log-level {error,warn,info,debug}。docs/troubleshooting/logs.md、docs/troubleshooting/request-id.md（本次仅知标题，未完整抓取）记录请求/会话 ID 的支持用途——官方原话：“Request IDs and session IDs are generated with every code suggestion, chat interaction, and agent session… Our team may ask you to provide these IDs when you report a bug.”
  • Hooks 兼具用户可控的观测/审计层：PostToolUse hook 接收 tool_output/tool_error/file_changes（含编辑前后完整 diff 内容），可用于审计日志；includeUserContext 元数据开关给每个 hook 事件附加 userEmail/modelName/timestamp；includeConversationData（仅 Stop 事件）暴露整个回合的 userPrompt/agentTextResponse/agentCodeResponse，用于合规日志——本质是通过用户自写脚本实现的一等结构化 trace 导出机制，详细文档于 docs/03_hooks.md、docs/04_hooks-examples.md。
  • 未找到 Augment 自身后端 trace 存储/分析格式的公开披露（仅知客户端追踪了什么，不知后端 APM 系统如何摄取/存储——大概率是专有或第三方 APM，未公开）。

安全与权限（审批门、密钥管理）

  • 工具权限 DSL 主体已在”工具体系”一节详述（allow/deny/ask-user/webhook-policy/script-policy，租户级覆盖，first-match-wins）。以下为该节未覆盖的安全相关细节：
    • 配置优先级明确为管理员控制设计：/etc/augment/settings.json（Linux/macOS）/ C:\ProgramData\Augment\settings.json（Windows）被文档标注为”immutable”且位于优先级最顶层——即不能被 workspace 或用户设置覆盖，给企业/管理员策略对工具权限和 hooks 的硬性否决权（docs/03_hooks.md）。
    • ask-user 模式在非交互（--print）模式下自动拒绝——一个安全默认选择，防止自动化流水线在无人审批时静默挂起或默认放行（docs/02_permissions.md）。
    • 交互式审批 UI：[A]llow [D]eny，Esc = deny（转义键默认拒绝，非默认允许）。
    • Secrets Manager 文档位于 /setup-augment/user-secrets（仅知 llms.txt 标题：“Securely store and manage secrets for your development environment, including API keys, tokens, and credentials”——本次未完整抓取，标记为跟进项）。
    • 认证 token 存储：bundle 确认登录会话存储于 augmentSessionJson（从 augmentCacheDir 加载），可通过 --augment-session-json <json-or-path> 或环境变量 AUGMENT_SESSION_AUTH 设置；auggie token print 输出本地存储的会话 JSON（供脚本/自动化使用——一个明确文档化、非我们自行发现的敏感数据处理设计）；auggie token revoke 吊销该用户的全部 token。
    • 网络/防火墙指引存在一手文档（/setup-augment/network-configuration、/setup-augment/static-ip-support——本次仅知标题，未完整抓取），面向需要给 Augment 流量做白名单的企业客户，侧面印证 Augment 预期被部署在受限企业网络内。
    • 工作区索引隐私声明（自述、未独立验证）：“Augment stores your code securely and privately… through a proof-of-possession API and… strict internal data minimization principles”（docs/10_workspace-indexing.md，链向 augmentcode.com/security，未完整抓取——标记为营销/信任中心措辞而非已验证机制）。

沙箱与执行隔离

  • 本地 Auggie CLI 未发现任何客户端沙箱。launch-process 直接在宿主机上执行 shell 命令（AUGMENT_AGENT=1 环境变量约定仅表示”由 agent 运行”，不隐含任何隔离）。本地执行的安全模型完全依赖权限 DSL（allow/deny/ask-user，正则过滤 shell 命令）——对 augment.mjs grep sandbox/docker/container/seccomp/chroot/jail 未发现披露或实现的隔离层，仅命中无关噪声：一处出处不明的 sandbox_status==="failed" 检查（可能是轮询远程/Cosmos 环境状态，非本地沙箱）、一处内嵌 DOM 解析库的 sandbox HTML 属性引用、以及内嵌 ML tokenizer 词表的噪声命中。
  • 隔离转而在 Cosmos 平台层实现，是一个明确文档化的一等概念：docs/cosmos/environments/* 描述”Cloud Environments”（Augment 托管的计算沙箱+文件系统，llms.txt 标题：“A Augment hosted compute environment and filesystem for your agent to run”）与”Self-hosted Environments”（客户自有 VM/物理基础设施，经由一个 daemon）——本次未完整抓取，标记为 stage-2 若需深挖沙箱/隔离细节的正确跟进目标。结合命名（“Cloud Environment”、“self-hosted daemons”）及 docs/17_workers-subagents.md 中”每个 Worker 拥有自己的 VM 和 Environment”的表述，Cosmos worker 几乎肯定运行在按会话隔离的 VM 中，但底层隔离技术（VM hypervisor / container / microVM）未披露。
  • 结论：CLI = 无隔离（依赖权限门控）；Cosmos = 按会话 VM/云环境（设计已确认，实现技术未披露）。

与模型的协同设计

  • Augment 明确以模型无关为设计原则并将其作为战略卖点营销：“Auggie isn’t bound to one model provider… the Context Engine sits in front of whichever frontier model you pick”（blog-auggie-beats-claude-code-cost-quality.md）。公开跑分对比覆盖 Opus 4.7、Sonnet 4.6、GPT 5.5、GPT 5.4、Gemini 3.1、Gemini Flash 3.0、Kimi K2.6——Anthropic、OpenAI、Google、Moonshot 均为一等公民，非陪衬。
  • 刻意的按角色模型分级已内建于内建 subagent（见 Router 章节）：高频、最可并行的 context-gathering 角色固定用 gemini-3-1-flash-lite-preview，而 validate 用 claude-sonnet-4-6——即 Augment 依据成本/质量权衡为不同子任务角色选择不同的模型家族/尺寸，而非交由用户选择。
  • Prism（见 Router 章节）是最深的模型协同设计披露：一个专职轻量规划器模型置于用户可见的模型选择之前，做带缓存驱逐成本感知的分回合路由——这是围绕特定模型厂商 prompt-caching 经济学（Anthropic/OpenAI/Google 实现方式各不相同）构建的一套实打实的基础设施，“仅当切换的预期收益超过约 10 倍缓存驱逐成本时才切换”是对该机制的直接适配。
  • BYOK（自带密钥）支持：bundle 引用 this.state.byokKeys，确认客户可提供自己的模型厂商 API key 而非经由 Augment 自身的模型访问路由——本次未找到完整描述 BYOK 配置的文档页，标记为跟进项。
  • auggie models list --full-info 以结构化 JSON 暴露”cost tiers, effort levels, and the account default model”（docs/08_reference.md）——即 Augment 追踪并暴露一个”per-model effort level”概念（大概率映射到各厂商不同实现的 reasoning-effort/thinking-budget 参数），又一处厂商感知而非通用化模型集成的证据。

轨迹利用（session/trajectory 是否反哺训练/评测）

  • 未发现用户会话轨迹反哺模型训练的证据（博客或文档中均无 RLHF-from-usage 披露、无基于轨迹微调的声明）。
  • 内部 benchmark 流水线已披露，形态上是轨迹驱动的，但属于内部 eval 方法论，不是用户轨迹驱动的训练闭环：Prism 博客描述了一套将某大型 Go 仓库的历史 PR 转换为合成多轮开发者对话的内部多轮 coding benchmark（“Each task starts the agent at the PR’s base commit and queues the full conversation in one session: the agent navigates the codebase, edits files, runs tools, and produces a final diff… An LLM judge model then scores that diff against the original PR on correctness, completeness, code reuse, best practices, and unsolicited documentation, returning an aggregate score in [-1, 1]”）。这是用历史轨迹（真实 PR）构建的 eval 基础设施，用于验证 Prism 的路由质量——不是用户会话轨迹，也不是训练信号（是 LLM-judge 打分对比，用于决定该上线哪些模型/配置，而非梯度更新）。
  • 会话数据（.augment/sessions/*.json，见记忆章节）本地优先、用户自有；auggie session share 生成”可分享链接”，暗示会话可以按需上传/分享给 Augment 后端，但未找到该数据被用于分享这一显式用户动作之外（如支持/协作用途）的证据，更没有证据表明其被用于模型改进。
  • 结论：基于历史轨迹的内部 eval 流水线已确认且有详细披露（Prism 博客）；轨迹反哺训练的闭环未披露/未找到。

与同类 harness 的关键差异（1-3 条，可以先留一句概述，后续 synthesis 阶段会做跨 harness 对比）

  • 与 Claude Code/Amp 等相比，Augment 把”模型选择”本身做成了一个独立的、服务端专有的路由问题（Prism），且刻意与 prompt-cache 经济学耦合设计——这在已调研的同类 harness 中是独有的深度。
  • 系统提示词服务端组装（而非随客户端 bundle 分发）是与多数开源/半开源 harness（提示词随代码可读）的显著架构差异，代价是本 dossier 无法获得顶层提示词原文。
  • Skills/Rules/Commands 三层区分 + 显式兼容 Claude Code 目录布局，体现了 harness 生态趋同（agentskills.io 标准 + .claude//.agents/ 路径复用），跨 harness 对比留待 synthesis 阶段。

原始源码定位

  • repo: 无公开源码；GitHub github.com/augmentcode/auggie（公开，100% Shell，仅插件市场/示例命令，非 harness 源码）；真实客户端为闭源 npm 包 @augmentcode/auggie
  • commit/version analyzed: @augmentcode/auggie@0.32.0（tarball shasum 70e0311f6ed8303520a912d485aa788de94fb9db），2026-07-07 通过 npm pack 拉取；bundle 内嵌 Sentry debug ID 80d4e217-3600-5b6f-af62-f9e588b66d22
  • 关键文件列表（相对路径，均在解包后的 package/ 下，未拷入本仓库，可用上述 npm pack 命令复现）：
    • package/augment.mjs — 单文件 ~12MB/8173 行 minified bundle，本 dossier 全部源码级论断的唯一代码来源
    • package/package.json — engines/bin 元信息
    • package/README.md、package/LICENSE.md

一手源存档（sources/）

/Users/zhao/projects/self-wiki/ai-research/sources/harness/augment-code/ 下：

  • NOTES.md — stage-1 完整调研笔记（176 行，本 dossier 的直接依据）
  • blog-auggie-beats-claude-code-cost-quality.md — 官方博客，Terminal-Bench-2.0/SWE-Bench-Pro 成本对比表
  • blog-prism-model-routing.md — 官方博客，Prism 模型路由器详细设计（本次调研信息量最大的单篇一手材料）
  • docs/01_overview.md … docs/17_workers-subagents.md — docs.augmentcode.com 抓取的 17 篇一手文档（overview、permissions、hooks×2、subagents、skills、custom-commands、CLI reference、rules、workspace-indexing、interactive、integrations、context-engine how-it-works、ACP agent 模式、SDK、Cosmos getting-started、Cosmos workers/subagents）
  • extracted-from-npm-bundle/subagent-prompts.md — 从 augment.mjs 逐字提取的五个内建 subagent 注册配置 + 完整系统提示词（research/plan/code/validate/context-gathering）
  • extracted-subagent-context-gathering-prompt.txt — context-gathering 提示词的早期/部分提取版本（已被上条文件覆盖，保留作发现轨迹记录）

stage-2 遗留跟进项（NOTES.md 明确标注未完整抓取，本 dossier 对应章节已标注”未验证/标题级”）：cosmos/experts-code-review.md（共享 review memory）、cosmos/experts-verifier.md、cosmos/experts-risk-analyzer.md、cosmos/environments/cloud.md、cosmos/environments/daemons.md、setup-augment/user-secrets.md、setup-augment/network-configuration.md、setup-augment/static-ip-support.md、cli/sdk-python.md、cli/sdk-typescript.md。

关系图谱

反向链接