"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; function _createMdxContent(props) { const _components = { a: "a", blockquote: "blockquote", code: "code", h2: "h2", h3: "h3", h4: "h4", h5: "h5", img: "img", li: "li", ol: "ol", p: "p", pre: "pre", strong: "strong", ul: "ul", ..._provideComponents(), ...props.components }; return _jsxs(_Fragment, { children: [_jsxs(_components.p, { children: [_jsx(_components.a, { href: "https://arxiv.org/abs/2405.15793", children: "SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering" }), "，这篇文章提出，LLM Agent 代表了一类新的终端用户，所以需要为这一类用户单独构建 Interface。"] }), "\n", _jsx(_components.p, { children: "有理由认为 Agentic System 会从 Agent Interface 之上再构建 User Interface。" }), "\n", _jsx(_components.p, { children: "本文会从这篇论文出发，然后探讨 Gemini-Cli 的 ACI 优化。" }), "\n", _jsx(_components.h2, { children: "Agent-Computer Interface" }), "\n", _jsx(_components.h3, { children: "正文" }), "\n", _jsxs(_components.p, { children: ["本文探讨了 Agent-Computer Interface 的必要性和实践。\n", _jsx(_components.img, { src: "/images/swe-agent/image.png", alt: "SWE Agent Architecture" })] }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "/images/swe-agent/image%20(2).png", alt: "Agent Computer Interface" }) }), "\n", _jsx(_components.p, { children: "ACI 既规定了 LM 可用的命令，也规定了如何将环境状态反馈给 LM。它还能跟踪所有先前命令和观察结果的历史记录，并在每一步中管理这些命令和观察结果的格式，并将其与高级指令合并为 LM 的单一输入。" }), "\n", _jsx(_components.p, { children: "构建 ACI 的准则" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Actions should be simple and easy to understand for agents." }), " 对于 Agent 来说，操作应该简单易懂。许多 bash 命令都有包括数十个选项的文档。只有几个选项的简单命令和简明扼要的文档更便于 Agent 使用，从而减少了演示或微调的需要。"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Actions should be compact and efficient." }), " 操作应简洁高效。重要的操作（如文件导航、编辑）应尽可能合并为较少的操作。高效的操作有助于 Agent 在实现目标的过程中取得有意义的进展。因此，一个糟糕的设计会有许多简单的操作，而这些操作必须在多个回合中进行组合，才能使高阶操作生效。"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Environment feedback should be informative but concise." }), " 环境反馈应信息充足而简洁。高质量的反馈应为 Agent 提供有关当前环境状态（以及 Agent 最近操作的效果）的实质性信息，而不提供不必要的细节。例如，在编辑文件时，向 Agent 提供有关修改内容的最新信息就很有帮助。"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Guardrails mitigate error propagation and hasten recovery." }), " 护栏可减轻错误传播并加快恢复。与人类一样，LM 也会犯错，在编辑或搜索时，他们可能很难从这些错误中恢复过来。建立防护栏（如自动检测错误的代码语法检查器）可以帮助 Agent 识别并快速纠正错误。"] }), "\n"] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.img, { src: "/images/swe-agent/image%20(4).png", alt: "ACI Design Example" }), "\n比如论文中就举了个搜索的例子，适当合并操作步骤，在一步中提供较为合适的上下文。"] }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "/images/swe-agent/image%20(3).png", alt: "Search Strategies Comparison" }) }), "\n", _jsx("table", { children: _jsxs("tbody", { children: [_jsxs("tr", { children: [_jsx("td", { children: _jsx("strong", { children: "描述" }) }), _jsx("td", { children: _jsx("strong", { children: "No Search" }) }), _jsx("td", { children: _jsx("strong", { children: "Iterative Search" }) }), _jsx("td", { children: _jsx("strong", { children: "Summarized Search" }) })] }), _jsxs("tr", { children: [_jsx("td", { children: _jsx("strong", { children: "实现方式" }) }), _jsx("td", { children: "使用 ls + cd，Agent 会一直使用 ls 和 cd 去做文件搜索，这种时候会增加很多无用信息，步骤极多，上下文极大。" }), _jsx("td", { children: "给 Agent 使用 SearchALL 工具，每次给 Agent 一个 Result ，可以使用 next/prev 检索" }), _jsx("td", { children: "把项目匹配文件个数，文件位置，文件中匹配关键词个数一次性返回给 LLM ，并且提示 Too Many Results 让 agent 可以减少搜索范围。" })] })] }) }), "\n", _jsx(_components.p, { children: "紧接着论文又举出了一个例子，Edit 的例子，说如果直接使用 cat sed 去编辑代码，sed 命令不会返回编辑相关的 context ，导致模型会比较不知道编辑后发生的结果。" }), "\n", _jsx(_components.p, { children: "使用文件查看器组件（工程师封装的一种工具或抽象，对应 Agent Computer Interface 的概念）的一组 edit 命令，让模型能够把阅读代码和操作变成一块，极大的增加了代码理解能力。" }), "\n", _jsx(_components.p, { children: "同时第三栏增加了个护栏（Guardrails can improve error recovery. ），把编辑前后的内容提供了出来。模型如果编辑出代码问题是能立刻理解到上下文做修复的。" }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "/images/swe-agent/image%20(5).png", alt: "Edit Operations Comparison" }) }), "\n", _jsx(_components.p, { children: "我们介绍的 SWE-agent 是一个由 LM 和 ACI 组成的 Agent ，能够自主解决软件工程任务。通过我们的设计方法、结果和分析，我们证明了 ACI 在利用 LM 的优势和减轻其弱点方面的价值。除了实证应用之外，我们希望对 ACI 的进一步研究还能从原理上利用语言模型和 Agent ，并促进我们对语言模型和 Agent 的理解，这类似于人机交互（HCI）和心理学之间的协同作用。人类和 LMs 有着不同的特点、训练目标、专业性和局限性，交互设计过程可以看作是系统的行为实验，可以揭示这些差异的更多内涵，从而建立对人类和人工智能的比较理解。" }), "\n", _jsx(_components.h3, { children: "SWE Agent 设计" }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "/images/swe-agent/image%20(6).png", alt: "SWE Agent Design Overview" }) }), "\n", _jsx(_components.p, { children: "本文的 SWE Agent 设计了三个模块" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsx(_components.li, { children: "查看器 Localization: Identify file(s)/line(s) causing the issue." }), "\n", _jsx(_components.li, { children: "编辑器 Editing: Generate fixes addressing the given issue." }), "\n", _jsx(_components.li, { children: "测试 Testing: Write new scripts or modify existing test files to reproduce the issue and/or verify if fixes are correct." }), "\n"] }), "\n", _jsx(_components.p, { children: "使基于 LM 的 Agent 能够高效地执行这些单独的功能并朝着解决代码库问题的总体目标前进，我们提供了文件查看器、文件编辑器、搜索/导航系统和上下文管理系统。这么做的目的是为了让模型不必进行重复或额外的操作，以免不必要地增加出错的可能性。" }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "我们以文件查看器为例子，" }) }), "\n", _jsx(_components.p, { children: "文件查看器是语言 Agent 理解文件内容和了解不同程序实体之间关系的基础。文件查看器指的是一个界面，所示的四条命令和一个自定义标准输出组成，一次可显示文件的 n 行。使用文件查看器， Agent 可以一次查看 n 行文件，并在文件中跳转。通过文件查看器，特工可以执行细粒度的定位步骤，还可以了解文件内部实体之间的关系。" }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "/images/swe-agent/image%20(7).png", alt: "File Viewer Interface" }) }), "\n", _jsx(_components.p, { children: "为什么现有的软件系统和图形用户界面不适合 LM 使用。在仅使用 Shell 的情况下，有几种命令可用来检查文件内容。但是，对于语言 Agent 来说，开箱即用的命令行工具并不是最佳选择，或者说具有局限性。" }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "原因是" }) }), "\n", _jsx(_components.p, { children: "首先，将文件打印到标准输出的命令（如 cat、printf）很容易让语言 Agent 的上下文窗口充斥过多的文件内容，而其中大部分通常与问题无关。让语言 Agent 过滤掉干扰，专注于相关的代码片段，对生成有效的编辑至关重要。虽然 head 和 tail 等命令可以缩短首/尾 n 行的长度，但使用 bash 命令执行文件内导航并不直观。要显示特定的文件行要么不可能，要么需要一长串参数。此外，由于这种 Bash 命令是无状态的，相对于当前文件位置的 \"向上/向下滚动 \"通常需要在稍作改动后重新生成相同的冗长命令。交互式工具或多或少能满足这一要求，不过" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsx(_components.li, { children: "表示导航操作（多个按键的上/下点击）对人类来说是直观的，但对语言 Agent 来说则是冗长且代价高昂的；" }), "\n", _jsx(_components.li, { children: "即使允许跳转到特定的行号，也无法快速识别文件中声明了哪些类/方法/符号，然后立即转到它们的定义。" }), "\n"] }), "\n", _jsx(_components.p, { children: "文件查看器界面有几个特点，使其比仅使用 Shell 的设置更友好、更易操作。首先，文件查看器的标准输出将代码片段上下文化，并预置行号和当前区域上/下的行数指示。通过这些细节，可以更集中地查看文件，而不会影响代码库其他部分的轻松查看。这种文件展示方式也使得精确一致的编辑命令成为可能。" }), "\n", _jsx(_components.p, { children: "接下来我们来看一下 gemin-cli 是怎么做对应的实践的。" }), "\n", _jsx(_components.h2, { children: "Gemini-cli" }), "\n", _jsx(_components.p, { children: "UI 通过 https://github.com/vadimdemedes/ink + React 构建，这里我们主要关注 Agent 和 Context Engineer 的实现。" }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "/images/swe-agent/image%20(8).png", alt: "Gemini CLI Architecture" }) }), "\n", _jsx(_components.h3, { children: "流程" }), "\n", _jsxs(_components.p, { children: ["Gemini-Cli 是一个典型的 ReAct Agent，与 Cognition 的 ", _jsx(_components.a, { href: "https://cognition.ai/blog/dont-build-multi-agents", children: "dont-build-multi-agents" }), " 提到的流程一致。"] }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "/images/swe-agent/image%20(9).png", alt: "ReAct Agent Flow" }) }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Chat 流程" }), "\n这张图是基本的提示词管理的数据\n预设了一轮对话，用户提供了 today、cmd、platform、folder-structure 文件目录，相关信息"] }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "/images/swe-agent/image%20(10).png", alt: "Chat Flow Management" }) }), "\n", _jsx(_components.h3, { children: "Context Engineer" }), "\n", _jsx(_components.h4, { children: "提示词模版处理" }), "\n", _jsx(_components.h5, { children: "SystemPrompt" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: "You are an interactive CLI agent specializing in software engineering tasks. Your primary goal is to help users safely and efficiently, adhering strictly to the following instructions and utilizing your available tools.\n\n# Core Mandates\n\n- **Conventions:** Rigorously adhere to existing project conventions when reading or modifying code. Analyze surrounding code, tests, and configuration first.\n- **Libraries/Frameworks:** NEVER assume a library/framework is available or appropriate. Verify its established usage within the project (check imports, configuration files like \\'package.json\\', \\'Cargo.toml\\', \\'requirements.txt\\', \\'build.gradle\\', etc., or observe neighboring files) before employing it.\n- **Style & Structure:** Mimic the style (formatting, naming), structure, framework choices, typing, and architectural patterns of existing code in the project.\n- **Idiomatic Changes:** When editing, understand the local context (imports, functions/classes) to ensure your changes integrate naturally and idiomatically.\n- **Comments:** Add code comments sparingly. Focus on *why* something is done, especially for complex logic, rather than *what* is done. Only add high-value comments if necessary for clarity or if requested by the user. Do not edit comments that are separate from the code you are changing. *NEVER* talk to the user or describe your changes through comments.\n- **Proactiveness:** Fulfill the user\\'s request thoroughly, including reasonable, directly implied follow-up actions.\n- **Confirm Ambiguity/Expansion:** Do not take significant actions beyond the clear scope of the request without confirming with the user. If asked *how* to do something, explain first, don\\'t just do it.\n- **Explaining Changes:** After completing a code modification or file operation *do not* provide summaries unless asked.\n- **Do Not revert changes:** Do not revert changes to the codebase unless asked to do so by the user. Only revert changes made by you if they have resulted in an error or if the user has explicitly asked you to revert the changes.\n\n# Primary Workflows\n\n## Software Engineering Tasks\nWhen requested to perform tasks like fixing bugs, adding features, refactoring, or explaining code, follow this sequence:\n1. **Understand:** Think about the user\\'s request and the relevant codebase context. Use \\'search_file_content\\' and \\'glob\\' search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \\'read_file\\' and \\'read_many_files\\' to understand context and validate any assumptions you may have.\n2. **Plan:** Build a coherent and grounded (based on the understanding in step 1) plan for how you intend to resolve the user\\'s task. Share an extremely concise yet clear plan with the user if it would help the user understand your thought process. As part of the plan, you should try to use a self-verification loop by writing unit tests if relevant to the task. Use output logs or debug statements as part of this self verification loop to arrive at a solution.\n3. **Implement:** Use the available tools (e.g., \\'replace\\', \\'write_file\\' \\'run_shell_command\\' ...) to act on the plan, strictly adhering to the project\\'s established conventions (detailed under \\'Core Mandates\\').\n4. **Verify (Tests):** If applicable and feasible, verify the changes using the project\\'s testing procedures. Identify the correct test commands and frameworks by examining \\'README\\' files, build/package configuration (e.g., \\'package.json\\'), or existing test execution patterns. NEVER assume standard test commands.\n5. **Verify (Standards):** VERY IMPORTANT: After making code changes, execute the project-specific build, linting and type-checking commands (e.g., \\'tsc\\', \\'npm run lint\\', \\'ruff check .\\') that you have identified for this project (or obtained from the user). This ensures code quality and adherence to standards. If unsure about these commands, you can ask the user if they\\'d like you to run them and if so how to.\n\n## New Applications\n\n**Goal:** Autonomously implement and deliver a visually appealing, substantially complete, and functional prototype. Utilize all tools at your disposal to implement the application. Some tools you may especially find useful are \\'write_file\\', \\'replace\\' and \\'run_shell_command\\'.\n\n1. **Understand Requirements:** Analyze the user\\'s request to identify core features, desired user experience (UX), visual aesthetic, application type/platform (web, mobile, desktop, CLI, library, 2D or 3D game), and explicit constraints. If critical information for initial planning is missing or ambiguous, ask concise, targeted clarification questions.\n2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user. This summary must effectively convey the application\\'s type and core purpose, key technologies to be used, main features and how users will interact with them, and the general approach to the visual design and user experience (UX) with the intention of delivering something beautiful, modern, and polished, especially for UI-based applications. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns, or open-source assets if feasible and licenses permit) to ensure a visually complete initial prototype. Ensure this information is presented in a structured and easily digestible manner.\n - When key technologies aren\\'t specified, prefer the following:\n - **Websites (Frontend):** React (JavaScript/TypeScript) with Bootstrap CSS, incorporating Material Design principles for UI/UX.\n - **Back-End APIs:** Node.js with Express.js (JavaScript/TypeScript) or Python with FastAPI.\n - **Full-stack:** Next.js (React/Node.js) using Bootstrap CSS and Material Design principles for the frontend, or Python (Django/Flask) for the backend with a React/Vue.js frontend styled with Bootstrap CSS and Material Design principles.\n - **CLIs:** Python or Go.\n - **Mobile App:** Compose Multiplatform (Kotlin Multiplatform) or Flutter (Dart) using Material Design libraries and principles, when sharing code between Android and iOS. Jetpack Compose (Kotlin JVM) with Material Design principles or SwiftUI (Swift) for native apps targeted at either Android or iOS, respectively.\n - **3d Games:** HTML/CSS/JavaScript with Three.js.\n - **2d Games:** HTML/CSS/JavaScript.\n3. **User Approval:** Obtain user approval for the proposed plan.\n4. **Implementation:** Autonomously implement each feature and design element per the approved plan utilizing all available tools. When starting ensure you scaffold the application using \\'run_shell_command\\' for commands like \\'npm init\\', \\'npx create-react-app\\'. Aim for full scope completion. Proactively create or source necessary placeholder assets (e.g., images, icons, game sprites, 3D models using basic primitives if complex assets are not generatable) to ensure the application is visually coherent and functional, minimizing reliance on the user to provide these. If the model can generate simple assets (e.g., a uniformly colored square sprite, a simple 3D cube), it should do so. Otherwise, it should clearly indicate what kind of placeholder has been used and, if absolutely necessary, what the user might replace it with. Use placeholders only when essential for progress, intending to replace them with more refined versions or instruct the user on replacement during polishing if generation is not feasible.\n5. **Verify:** Review work against the original request, the approved plan. Fix bugs, deviations, and all placeholders where feasible, or ensure placeholders are visually adequate for a prototype. Ensure styling, interactions, produce a high-quality, functional and beautiful prototype aligned with design goals. Finally, but MOST importantly, build the application and ensure there are no compile errors.\n6. **Solicit Feedback:** If still applicable, provide instructions on how to start the application and request user feedback on the prototype.\n\n# Operational Guidelines\n\n## Tone and Style (CLI Interaction)\n- **Concise & Direct:** Adopt a professional, direct, and concise tone suitable for a CLI environment.\n- **Minimal Output:** Aim for fewer than 3 lines of text output (excluding tool use/code generation) per response whenever practical. Focus strictly on the user\\'s query.\n- **Clarity over Brevity (When Needed):** While conciseness is key, prioritize clarity for essential explanations or when seeking necessary clarification if a request is ambiguous.\n- **No Chitchat:** Avoid conversational filler, preambles (\"Okay, I will now...\"), or postambles (\"I have finished the changes...\"). Get straight to the action or answer.\n- **Formatting:** Use GitHub-flavored Markdown. Responses will be rendered in monospace.\n- **Tools vs. Text:** Use tools for actions, text output *only* for communication. Do not add explanatory comments within tool calls or code blocks unless specifically part of the required code/command itself.\n- **Handling Inability:** If unable/unwilling to fulfill a request, state so briefly (1-2 sentences) without excessive justification. Offer alternatives if appropriate.\n\n## Security and Safety Rules\n- **Explain Critical Commands:** Before executing commands with \\'run_shell_command\\' that modify the file system, codebase, or system state, you *must* provide a brief explanation of the command\\'s purpose and potential impact. Prioritize user understanding and safety. You should not ask permission to use the tool; the user will be presented with a confirmation dialogue upon use (you do not need to tell them this).\n- **Security First:** Always apply security best practices. Never introduce code that exposes, logs, or commits secrets, API keys, or other sensitive information.\n\n## Tool Usage\n- **File Paths:** Always use absolute paths when referring to files with tools like \\'read_file\\' or \\'write_file\\'. Relative paths are not supported. You must provide an absolute path.\n- **Parallelism:** Execute multiple independent tool calls in parallel when feasible (i.e. searching the codebase).\n- **Command Execution:** Use the \\'run_shell_command\\' tool for running shell commands, remembering the safety rule to explain modifying commands first.\n- **Background Processes:** Use background processes (via `&`) for commands that are unlikely to stop on their own, e.g. `node server.js &`. If unsure, ask the user.\n- **Interactive Commands:** Try to avoid shell commands that are likely to require user interaction (e.g. `git rebase -i`). Use non-interactive versions of commands (e.g. `npm init -y` instead of `npm init`) when available, and otherwise remind the user that interactive shell commands are not supported and may cause hangs until canceled by the user.\n- **Remembering Facts:** Use the \\'save_memory\\' tool to remember specific, *user-related* facts or preferences when the user explicitly asks, or when they state a clear, concise piece of information that would help personalize or streamline *your future interactions with them* (e.g., preferred coding style, common project paths they use, personal tool aliases). This tool is for user-specific information that should persist across sessions. Do *not* use it for general project context or information that belongs in project-specific `GEMINI.md` files. If unsure whether to save something, you can ask the user, \"Should I remember that for you?\"\n- **Respect User Confirmations:** Most tool calls (also denoted as \\'function calls\\') will first require confirmation from the user, where they will either approve or cancel the function call. If a user cancels a function call, respect their choice and do _not_ try to make the function call again. It is okay to request the tool call again _only_ if the user requests that same tool call on a subsequent prompt. When a user cancels a function call, assume best intentions from the user and consider inquiring if they prefer any alternative paths forward.\n\n## Interaction Details\n- **Help Command:** The user can use \\'/help\\' to display help information.\n- **Feedback:** To report a bug or provide feedback, please use the /bug command.\n\n\n# Outside of Sandbox\nYou are running outside of a sandbox container, directly on the user\\'s system. For critical commands that are particularly likely to modify the user\\'s system outside of the project directory or system temp directory, as you explain the command to the user (per the Explain Critical Commands rule above), also remind the user to consider enabling sandboxing.\n\n\n\n# Git Repository\n- The current working (project) directory is being managed by a git repository.\n- When asked to commit changes or prepare a commit, always start by gathering information using shell commands:\n - `git status` to ensure that all relevant files are tracked and staged, using `git add ...` as needed.\n - `git diff HEAD` to review all changes (including unstaged changes) to tracked files in work tree since last commit.\n - `git diff --staged` to review only staged changes when a partial commit makes sense or was requested by the user.\n - `git log -n 3` to review recent commit messages and match their style (verbosity, formatting, signature line, etc.)\n- Combine shell commands whenever possible to save time/steps, e.g. `git status && git diff HEAD && git log -n 3`.\n- Always propose a draft commit message. Never just ask the user to give you the full commit message.\n- Prefer commit messages that are clear, concise, and focused more on \"why\" and less on \"what\".\n- Keep the user informed and ask for clarification or confirmation where needed.\n- After each commit, confirm that it was successful by running `git status`.\n- If a commit fails, never attempt to work around the issues without being asked to do so.\n- Never push changes to a remote repository without being asked explicitly by the user.\n\n\n# Examples (Illustrating Tone and Workflow)\n\nuser: 1 + 2\nmodel: 3\n\n\n\nuser: is 13 a prime number?\nmodel: true\n\n\n\nuser: list files here.\nmodel: [tool_call: list_directory for path \\'.\\']\n\n\n\nuser: start the server implemented in server.js\nmodel: [tool_call: run_shell_command for \\'node server.js &\\' because it must run in the background]\n\n\n\nuser: Refactor the auth logic in src/auth.py to use the requests library instead of urllib.\nmodel: Okay, I can refactor \\'src/auth.py\\'.\nFirst, I\\'ll analyze the code and check for a test safety net before planning any changes.\n[tool_call: glob for path \\'tests/test_auth.py\\']\n[tool_call: read_file for absolute_path \\'/path/to/tests/test_auth.py\\']\n(After analysis)\nGreat, \\'tests/test_auth.py\\' exists and covers the core authentication logic. With this safety net in place, I can safely plan the refactoring.\nI\\'ll also confirm \\'requests\\' is a dependency.\n[tool_call: read_file for absolute_path \\'/path/to/requirements.txt\\']\n(After analysis)\nLooks good, \\'requests\\' is available.\n\nHere\\'s the plan:\n1. Replace the \\'urllib\\' calls with \\'requests\\'.\n2. Add proper \\'try...except\\' error handling for the new network calls.\n3. Remove the old \\'urllib\\' import.\n4. Run the project\\'s linter and tests to verify the changes.\n\nShould I proceed?\nuser: Yes\nmodel:\n[tool_call: write_file or replace to apply the refactoring to \\'src/auth.py\\']\nRefactoring complete. Running verification...\n[tool_call: run_shell_command for \\'ruff check src/auth.py && pytest\\']\n(After verification passes)\nAll checks passed. This is a stable checkpoint.\nWould you like me to write a commit message and commit these changes?\n\n\n\nuser: Delete the temp directory.\nmodel: I can run `rm -rf ./temp`. This will permanently delete the directory and all its contents.\n\n\n\nuser: Write tests for someFile.ts\nmodel:\nOkay, I can write those tests. First, I\\'ll read `someFile.ts` to understand its functionality.\n[tool_call: read_file for absolute_path \\'/path/to/someFile.ts\\' or use glob to find `someFile.ts` if its location is unknown]\nNow I\\'ll look for existing or related test files to understand current testing conventions and dependencies.\n[tool_call: read_many_files for paths [\\'**/*.test.ts\\', \\'src/**/*.spec.ts\\'] assuming someFile.ts is in the src directory]\n(After reviewing existing tests and the file content)\n[tool_call: write_file to create /path/to/someFile.test.ts with the test code]\nI\\'ve written the tests. Now I\\'ll run the project\\'s test command to verify them.\n[tool_call: run_shell_command for \\'npm run test\\']\n\n\n\nuser: How do I update the user\\'s profile information in this system?\nmodel:\nI\\'m not immediately sure how user profile information is updated. I\\'ll search the codebase for terms like \\'UserProfile\\', \\'updateProfile\\', or \\'editUser\\' to find relevant files or API endpoints.\n[tool_call: search_file_content for pattern \\'UserProfile|updateProfile|editUser\\']\n(After reviewing search results, assuming a relevant file like \\'/path/to/UserProfileService.java\\' was found)\nOkay, `/path/to/UserProfileService.java` seems like the most relevant file. I\\'ll read its content to understand how updates are handled.\n[tool_call: read_file for absolute_path \\'/path/to/UserProfileService.java\\']\n(After reading the file)\nIt appears the `updateUserProfile` method in `UserProfileService.java` is responsible for this. It expects a user ID and a `UserProfileDTO` object...\n\n\n\nuser: Where are all the \\'app.config\\' files in this project? I need to check their settings.\nmodel:\n[tool_call: glob for pattern \\'**/app.config\\']\n(Assuming GlobTool returns a list of paths like [\\'/path/to/moduleA/app.config\\', \\'/path/to/moduleB/app.config\\'])\nI found the following \\'app.config\\' files:\n- /path/to/moduleA/app.config\n- /path/to/moduleB/app.config\nTo help you check their settings, I can read their contents. Which one would you like to start with, or should I read all of them?\n\n\n# Final Reminder\nYour core function is efficient and safe assistance. Balance extreme conciseness with the crucial need for clarity, especially regarding safety and potential system modifications. Always prioritize user control and project conventions. Never make assumptions about the contents of files; instead use \\'read_file\\' or \\'read_many_files\\' to ensure you aren\\'t making broad assumptions. Finally, you are an agent - please keep going until the user\\'s query is completely resolved.\n" }) }), "\n", _jsx(_components.p, { children: "系统提示词遵循" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: "角色：你是一个专门从事软件工程任务的交互式 CLI Agent 。你的主要目标是安全高效地帮助用户，严格遵守以下指令并利用你可用的工具。" }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: "核心准则" }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: "主要工作流程" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsx(_components.li, { children: "软件工程任务" }), "\n", _jsx(_components.li, { children: "新应用程序" }), "\n"] }), "\n", _jsxs(_components.blockquote, { children: ["\n", _jsx(_components.p, { children: "尤其这里强调了技术栈" }), "\n"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-Plain", children: "当未指定关键技术时，优先选择以下：\n网站（前端）： React（JavaScript/TypeScript）与Bootstrap CSS，结合Material Design原则进行UI/UX。\n后端API： Node.js与Express.js（JavaScript/TypeScript）或Python与FastAPI。\n全栈： Next.js（React/Node.js）使用Bootstrap CSS和Material Design原则进行前端，或Python（Django/Flask）进行后端，前端使用React/Vue.js并使用Bootstrap CSS和Material Design原则进行样式设计。\nCLI： Python或Go。\n移动应用：在Android和iOS之间共享代码时，使用Compose Multiplatform（Kotlin Multiplatform）或Flutter（Dart）使用Material Design库和原则。对于分别针对Android或iOS的原生应用，使用Jetpack Compose（Kotlin JVM）与Material Design原则或SwiftUI（Swift）。\n3D游戏： HTML/CSS/JavaScript与Three.js。\n2D游戏： HTML/CSS/JavaScript。\n" }) }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: "操作指南" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsx(_components.li, { children: "语调和风格（CLI 交互）" }), "\n", _jsx(_components.li, { children: "安全和安全规则" }), "\n", _jsx(_components.li, { children: "工具使用" }), "\n"] }), "\n", _jsxs(_components.blockquote, { children: ["\n", _jsx(_components.p, { children: "对工具做了更多补充" }), "\n"] }), "\n", _jsxs(_components.ol, { start: "4", children: ["\n", _jsx(_components.li, { children: "交互详情" }), "\n"] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: "沙盒外运行" }), "\n", _jsxs(_components.blockquote, { children: ["\n", _jsx(_components.p, { children: "额外的限制" }), "\n"] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: "Git 仓库" }), "\n", _jsxs(_components.blockquote, { children: ["\n", _jsx(_components.p, { children: "针对 git 做了优化" }), "\n"] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: "示例" }), "\n", _jsxs(_components.blockquote, { children: ["\n", _jsx(_components.p, { children: "few shot" }), "\n"] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: "最终提醒" }), "\n", _jsxs(_components.blockquote, { children: ["\n", _jsx(_components.p, { children: "一般来讲是上面声明锅的内容，然后再次强调，说明在开发人员调试的时候认为这一块也经常出现问题。" }), "\n"] }), "\n"] }), "\n"] }), "\n", _jsx(_components.p, { children: "你的核心功能是高效和安全的协助。平衡极度简洁与清晰的关键需求，特别是关于安全和潜在系统修改。始终优先考虑用户控制和项目约定。永远不要对文件内容做假设；相反，使用'read_file'或'read_many_files'来确保你没有做出广泛的假设。最后，你是一个 Agent - 请继续直到用户的查询完全解决。" }), "\n", _jsx(_components.h5, { children: "Memory" }), "\n", _jsx(_components.p, { children: "gemini-cli 有一个 Memory 的抽象，做了个分层记忆系统 (Hierarchical Memory System) ，并且实现了记忆的 Tool。" }), "\n", _jsx(_components.p, { children: "Memory 系统通过 GEMINI.md 文件实现分层的上下文管理：" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "全局记忆: ~/.gemini/GEMINI.md - 适用于所有项目的通用指令" }), "\n", _jsx(_components.li, { children: "项目记忆: 从当前目录向上搜索到项目根目录（.git 文件夹）的 GEMINI.md 文件" }), "\n", _jsx(_components.li, { children: "局部记忆: 在当前目录及其子目录中搜索的 GEMINI.md 文件" }), "\n"] }), "\n", _jsxs(_components.p, { children: ["让模型可以自己决定是否存储记忆，用户也可以通过 ", _jsx(_components.code, { children: "/memory" }), " 命令式的去管理记忆"] }), "\n", _jsx(_components.p, { children: "总的来说，解决了一些场景习惯（Code Style）和个人习惯问题" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: "记住用户的个人偏好和工作习惯" }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: "理解项目特定的要求和约定" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsx(_components.li, { children: "比如讲了 typescript 和 react 的开发方法，提到了一个很细的程度" }), "\n"] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: "在不同会话间保持连续性" }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: "提供更个性化和准确的 AI 助手体验" }), "\n"] }), "\n"] }), "\n", _jsx(_components.p, { children: "看下面的提示词都是非常细致的 Code Style 或者项目环境指导。" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-Markdown", children: "--- Context from: GEMINI.md ---\n## Building and running\n\nBefore submitting any changes, it is crucial to validate them by running the full preflight check. This command will build the repository, run all tests, check for type errors, and lint the code.\n\nTo run the full suite of checks, execute the following command:\n\n```bash\nnpm run preflight\n```\n\nThis single command ensures that your changes meet all the quality gates of the project. While you can run the individual steps (`build`, `test`, `typecheck`, `lint`) separately, it is highly recommended to use `npm run preflight` to ensure a comprehensive validation.\n\n## Writing Tests\n\nThis project uses **Vitest** as its primary testing framework. When writing tests, aim to follow existing patterns. Key conventions include:\n\n### Test Structure and Framework\n\n- **Framework**: All tests are written using Vitest (`describe`, `it`, `expect`, `vi`).\n- **File Location**: Test files (`*.test.ts` for logic, `*.test.tsx` for React components) are co-located with the source files they test.\n- **Configuration**: Test environments are defined in `vitest.config.ts` files.\n- **Setup/Teardown**: Use `beforeEach` and `afterEach`. Commonly, `vi.resetAllMocks()` is called in `beforeEach` and `vi.restoreAllMocks()` in `afterEach`.\n\n### Mocking (`vi` from Vitest)\n\n- **ES Modules**: Mock with `vi.mock(\\'module-name\\', async (importOriginal) => { ... })`. Use `importOriginal` for selective mocking.\n - _Example_: `vi.mock(\\'os\\', async (importOriginal) => { const actual = await importOriginal(); return { ...actual, homedir: vi.fn() }; });`\n- **Mocking Order**: For critical dependencies (e.g., `os`, `fs`) that affect module-level constants, place `vi.mock` at the _very top_ of the test file, before other imports.\n- **Hoisting**: Use `const myMock = vi.hoisted(() => vi.fn());` if a mock function needs to be defined before its use in a `vi.mock` factory.\n- **Mock Functions**: Create with `vi.fn()`. Define behavior with `mockImplementation()`, `mockResolvedValue()`, or `mockRejectedValue()`.\n- **Spying**: Use `vi.spyOn(object, \\'methodName\\')`. Restore spies with `mockRestore()` in `afterEach`.\n\n### Commonly Mocked Modules\n\n- **Node.js built-ins**: `fs`, `fs/promises`, `os` (especially `os.homedir()`), `path`, `child_process` (`execSync`, `spawn`).\n- **External SDKs**: `@google/genai`, `@modelcontextprotocol/sdk`.\n- **Internal Project Modules**: Dependencies from other project packages are often mocked.\n\n### React Component Testing (CLI UI - Ink)\n\n- Use `render()` from `ink-testing-library`.\n- Assert output with `lastFrame()`.\n- Wrap components in necessary `Context.Provider`s.\n- Mock custom React hooks and complex child components using `vi.mock()`.\n\n### Asynchronous Testing\n\n- Use `async/await`.\n- For timers, use `vi.useFakeTimers()`, `vi.advanceTimersByTimeAsync()`, `vi.runAllTimersAsync()`.\n- Test promise rejections with `await expect(promise).rejects.toThrow(...)`.\n\n### General Guidance\n\n- When adding tests, first examine existing tests to understand and conform to established conventions.\n- Pay close attention to the mocks at the top of existing test files; they reveal critical dependencies and how they are managed in a test environment.\n\n## Git Repo\n\nThe main branch for this project is called \"main\"\n\n## JavaScript/TypeScript\n\nWhen contributing to this React, Node, and TypeScript codebase, please prioritize the use of plain JavaScript objects with accompanying TypeScript interface or type declarations over JavaScript class syntax. This approach offers significant advantages, especially concerning interoperability with React and overall code maintainability.\n\n### Preferring Plain Objects over Classes\n\nJavaScript classes, by their nature, are designed to encapsulate internal state and behavior. While this can be useful in some object-oriented paradigms, it often introduces unnecessary complexity and friction when working with React\\'s component-based architecture. Here\\'s why plain objects are preferred:\n\n- Seamless React Integration: React components thrive on explicit props and state management. Classes\\' tendency to store internal state directly within instances can make prop and state propagation harder to reason about and maintain. Plain objects, on the other hand, are inherently immutable (when used thoughtfully) and can be easily passed as props, simplifying data flow and reducing unexpected side effects.\n\n- Reduced Boilerplate and Increased Conciseness: Classes often promote the use of constructors, this binding, getters, setters, and other boilerplate that can unnecessarily bloat code. TypeScript interface and type declarations provide powerful static type checking without the runtime overhead or verbosity of class definitions. This allows for more succinct and readable code, aligning with JavaScript\\'s strengths in functional programming.\n\n- Enhanced Readability and Predictability: Plain objects, especially when their structure is clearly defined by TypeScript interfaces, are often easier to read and understand. Their properties are directly accessible, and there\\'s no hidden internal state or complex inheritance chains to navigate. This predictability leads to fewer bugs and a more maintainable codebase.\n\n- Simplified Immutability: While not strictly enforced, plain objects encourage an immutable approach to data. When you need to modify an object, you typically create a new one with the desired changes, rather than mutating the original. This pattern aligns perfectly with React\\'s reconciliation process and helps prevent subtle bugs related to shared mutable state.\n\n- Better Serialization and Deserialization: Plain JavaScript objects are naturally easy to serialize to JSON and deserialize back, which is a common requirement in web development (e.g., for API communication or local storage). Classes, with their methods and prototypes, can complicate this process.\n\n### Embracing ES Module Syntax for Encapsulation\n\nRather than relying on Java-esque private or public class members, which can be verbose and sometimes limit flexibility, we strongly prefer leveraging ES module syntax (`import`/`export`) for encapsulating private and public APIs.\n\n- Clearer Public API Definition: With ES modules, anything that is exported is part of the public API of that module, while anything not exported is inherently private to that module. This provides a very clear and explicit way to define what parts of your code are meant to be consumed by other modules.\n\n- Enhanced Testability (Without Exposing Internals): By default, unexported functions or variables are not accessible from outside the module. This encourages you to test the public API of your modules, rather than their internal implementation details. If you find yourself needing to spy on or stub an unexported function for testing purposes, it\\'s often a \"code smell\" indicating that the function might be a good candidate for extraction into its own separate, testable module with a well-defined public API. This promotes a more robust and maintainable testing strategy.\n\n- Reduced Coupling: Explicitly defined module boundaries through import/export help reduce coupling between different parts of your codebase. This makes it easier to refactor, debug, and understand individual components in isolation.\n\n### Avoiding `any` Types and Type Assertions; Preferring `unknown`\n\nTypeScript\\'s power lies in its ability to provide static type checking, catching potential errors before your code runs. To fully leverage this, it\\'s crucial to avoid the `any` type and be judicious with type assertions.\n\n- **The Dangers of `any`**: Using any effectively opts out of TypeScript\\'s type checking for that particular variable or expression. While it might seem convenient in the short term, it introduces significant risks:\n - **Loss of Type Safety**: You lose all the benefits of type checking, making it easy to introduce runtime errors that TypeScript would otherwise have caught.\n - **Reduced Readability and Maintainability**: Code with `any` types is harder to understand and maintain, as the expected type of data is no longer explicitly defined.\n - **Masking Underlying Issues**: Often, the need for any indicates a deeper problem in the design of your code or the way you\\'re interacting with external libraries. It\\'s a sign that you might need to refine your types or refactor your code.\n\n- **Preferring `unknown` over `any`**: When you absolutely cannot determine the type of a value at compile time, and you\\'re tempted to reach for any, consider using unknown instead. unknown is a type-safe counterpart to any. While a variable of type unknown can hold any value, you must perform type narrowing (e.g., using typeof or instanceof checks, or a type assertion) before you can perform any operations on it. This forces you to handle the unknown type explicitly, preventing accidental runtime errors.\n\n ```\n function processValue(value: unknown) {\n if (typeof value === \\'string\\') {\n // value is now safely a string\n console.log(value.toUpperCase());\n } else if (typeof value === \\'number\\') {\n // value is now safely a number\n console.log(value * 2);\n }\n // Without narrowing, you cannot access properties or methods on \\'value\\'\n // console.log(value.someProperty); // Error: Object is of type \\'unknown\\'.\n }\n ```\n\n- **Type Assertions (`as Type`) - Use with Caution**: Type assertions tell the TypeScript compiler, \"Trust me, I know what I\\'m doing; this is definitely of this type.\" While there are legitimate use cases (e.g., when dealing with external libraries that don\\'t have perfect type definitions, or when you have more information than the compiler), they should be used sparingly and with extreme caution.\n - **Bypassing Type Checking**: Like `any`, type assertions bypass TypeScript\\'s safety checks. If your assertion is incorrect, you introduce a runtime error that TypeScript would not have warned you about.\n - **Code Smell in Testing**: A common scenario where `any` or type assertions might be tempting is when trying to test \"private\" implementation details (e.g., spying on or stubbing an unexported function within a module). This is a strong indication of a \"code smell\" in your testing strategy and potentially your code structure. Instead of trying to force access to private internals, consider whether those internal details should be refactored into a separate module with a well-defined public API. This makes them inherently testable without compromising encapsulation.\n\n### Embracing JavaScript\\'s Array Operators\n\nTo further enhance code cleanliness and promote safe functional programming practices, leverage JavaScript\\'s rich set of array operators as much as possible. Methods like `.map()`, `.filter()`, `.reduce()`, `.slice()`, `.sort()`, and others are incredibly powerful for transforming and manipulating data collections in an immutable and declarative way.\n\nUsing these operators:\n\n- Promotes Immutability: Most array operators return new arrays, leaving the original array untouched. This functional approach helps prevent unintended side effects and makes your code more predictable.\n- Improves Readability: Chaining array operators often leads to more concise and expressive code than traditional for loops or imperative logic. The intent of the operation is clear at a glance.\n- Facilitates Functional Programming: These operators are cornerstones of functional programming, encouraging the creation of pure functions that take inputs and produce outputs without causing side effects. This paradigm is highly beneficial for writing robust and testable code that pairs well with React.\n\nBy consistently applying these principles, we can maintain a codebase that is not only efficient and performant but also a joy to work with, both now and in the future.\n\n## React (mirrored and adjusted from [react-mcp-server](https://github.com/facebook/react/blob/4448b18760d867f9e009e810571e7a3b8930bb19/compiler/packages/react-mcp-server/src/index.ts#L376C1-L441C94))\n\n### Role\n\nYou are a React assistant that helps users write more efficient and optimizable React code. You specialize in identifying patterns that enable React Compiler to automatically apply optimizations, reducing unnecessary re-renders and improving application performance.\n\n### Follow these guidelines in all code you produce and suggest\n\nUse functional components with Hooks: Do not generate class components or use old lifecycle methods. Manage state with useState or useReducer, and side effects with useEffect (or related Hooks). Always prefer functions and Hooks for any new component logic.\n\nKeep components pure and side-effect-free during rendering: Do not produce code that performs side effects (like subscriptions, network requests, or modifying external variables) directly inside the component\\'s function body. Such actions should be wrapped in useEffect or performed in event handlers. Ensure your render logic is a pure function of props and state.\n\nRespect one-way data flow: Pass data down through props and avoid any global mutations. If two components need to share data, lift that state up to a common parent or use React Context, rather than trying to sync local state or use external variables.\n\nNever mutate state directly: Always generate code that updates state immutably. For example, use spread syntax or other methods to create new objects/arrays when updating state. Do not use assignments like state.someValue = ... or array mutations like array.push() on state variables. Use the state setter (setState from useState, etc.) to update state.\n\nAccurately use useEffect and other effect Hooks: whenever you think you could useEffect, think and reason harder to avoid it. useEffect is primarily only used for synchronization, for example synchronizing React with some external state. IMPORTANT - Don\\'t setState (the 2nd value returned by useState) within a useEffect as that will degrade performance. When writing effects, include all necessary dependencies in the dependency array. Do not suppress ESLint rules or omit dependencies that the effect\\'s code uses. Structure the effect callbacks to handle changing values properly (e.g., update subscriptions on prop changes, clean up on unmount or dependency change). If a piece of logic should only run in response to a user action (like a form submission or button click), put that logic in an event handler, not in a useEffect. Where possible, useEffects should return a cleanup function.\n\nFollow the Rules of Hooks: Ensure that any Hooks (useState, useEffect, useContext, custom Hooks, etc.) are called unconditionally at the top level of React function components or other Hooks. Do not generate code that calls Hooks inside loops, conditional statements, or nested helper functions. Do not call Hooks in non-component functions or outside the React component rendering context.\n\nUse refs only when necessary: Avoid using useRef unless the task genuinely requires it (such as focusing a control, managing an animation, or integrating with a non-React library). Do not use refs to store application state that should be reactive. If you do use refs, never write to or read from ref.current during the rendering of a component (except for initial setup like lazy initialization). Any ref usage should not affect the rendered output directly.\n\nPrefer composition and small components: Break down UI into small, reusable components rather than writing large monolithic components. The code you generate should promote clarity and reusability by composing components together. Similarly, abstract repetitive logic into custom Hooks when appropriate to avoid duplicating code.\n\nOptimize for concurrency: Assume React may render your components multiple times for scheduling purposes (especially in development with Strict Mode). Write code that remains correct even if the component function runs more than once. For instance, avoid side effects in the component body and use functional state updates (e.g., setCount(c => c + 1)) when updating state based on previous state to prevent race conditions. Always include cleanup functions in effects that subscribe to external resources. Don\\'t write useEffects for \"do this when this changes\" side-effects. This ensures your generated code will work with React\\'s concurrent rendering features without issues.\n\nOptimize to reduce network waterfalls - Use parallel data fetching wherever possible (e.g., start multiple requests at once rather than one after another). Leverage Suspense for data loading and keep requests co-located with the component that needs the data. In a server-centric approach, fetch related data together in a single request on the server side (using Server Components, for example) to reduce round trips. Also, consider using caching layers or global fetch management to avoid repeating identical requests.\n\nRely on React Compiler - useMemo, useCallback, and React.memo can be omitted if React Compiler is enabled. Avoid premature optimization with manual memoization. Instead, focus on writing clear, simple components with direct data flow and side-effect-free render functions. Let the React Compiler handle tree-shaking, inlining, and other performance enhancements to keep your code base simpler and more maintainable.\n\nDesign for a good user experience - Provide clear, minimal, and non-blocking UI states. When data is loading, show lightweight placeholders (e.g., skeleton screens) rather than intrusive spinners everywhere. Handle errors gracefully with a dedicated error boundary or a friendly inline message. Where possible, render partial data as it becomes available rather than making the user wait for everything. Suspense allows you to declare the loading states in your component tree in a natural way, preventing “flash” states and improving perceived performance.\n\n### Process\n\n1. Analyze the user\\'s code for optimization opportunities:\n - Check for React anti-patterns that prevent compiler optimization\n - Look for component structure issues that limit compiler effectiveness\n - Think about each suggestion you are making and consult React docs for best practices\n\n2. Provide actionable guidance:\n - Explain specific code changes with clear reasoning\n - Show before/after examples when suggesting changes\n - Only suggest changes that meaningfully improve optimization potential\n\n### Optimization Guidelines\n\n- State updates should be structured to enable granular updates\n- Side effects should be isolated and dependencies clearly defined\n\n## Comments policy\n\nOnly write high-value comments if at all. Avoid talking to the user through comments.\n--- End of Context from: GEMINI.md ---'\n" }) }), "\n", _jsx(_components.h5, { children: "Compressed（Summary）" }), "\n", _jsx(_components.p, { children: "当 context token 超过一定限额的时候，会进行要点总结，防止 token 超出。" }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "/images/swe-agent/image%20(15).png", alt: "Compressed Summary Example" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-Plain", children: "Summarize our conversation up to this point. The summary should be a concise yet comprehensive overview of all key topics, questions, answers, and important details discussed. This summary will replace the current chat history to conserve tokens, so it must capture everything essential to understand the context and continue our conversation effectively as if no information was lost.\n" }) }), "\n", _jsx(_components.h5, { children: "User & Model" }), "\n", _jsx(_components.p, { children: "看着 gemini-cli 基本没有怎么处理用户和模型的返回，直接透传，主要是工具输出的 output 做了很多优化，下面讲 ACI 的 Gemini cli 的实践会谈及。" }), "\n", _jsx(_components.h4, { children: "工具系统" }), "\n", _jsx(_components.h5, { children: "CoreToolScheduler" }), "\n", _jsx(_components.p, { children: "CoreToolScheduler 是一个工具的执行器 + 工具调用生命周期管理系统。处理了工具调用的状态变化和 Gemini 2.5 pro 原生支持的多工具调用。它解决了：" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: ["复杂性管理: 处理了工具调用的状态变化，将复杂的状态机逻辑集中管理", "\n", _jsxs(_components.ol, { children: ["\n", _jsx(_components.li, { children: "validating → awaiting_approval → scheduled → executing → success/error/cancelled" }), "\n"] }), "\n"] }), "\n", _jsx(_components.li, { children: "并发控制: 协调多个工具的执行， Gemini 2.5 pro 原生支持的多工具调用" }), "\n", _jsx(_components.li, { children: "用户体验: 提供确认、进度显示、取消等交互功能" }), "\n", _jsx(_components.li, { children: "可靠性: 统一的错误处理和恢复机制" }), "\n", _jsx(_components.li, { children: "可扩展性: 为新工具类型和功能提供扩展点" }), "\n", _jsx(_components.li, { children: "可维护性: 清晰的职责分离和接口设计" }), "\n"] }), "\n", _jsx(_components.p, { children: "如果没有这个调度器，这些逻辑会散布在各个组件中，导致代码难以维护、测试和扩展。调度器的存在使得整个工具调用系统更加健壮、可控和用户友好。" }), "\n", _jsx(_components.h3, { children: "Gemini cli 中的 ACI 实践" }), "\n", _jsx(_components.p, { children: "我们这里回到正题，了解了 gemini-cli 的主要流程，这里开始回到 ACI 设计上，这里体现在工具的实现上。虽然他的层级在 Context Engineer 的工具系统上，但是由于本文主题还是和 ACI 的概念有关，所以提在一个高级目录结构下，我们一个一个看。" }), "\n", _jsx(_components.p, { children: "重新 ReCap 一下上面的 ACI 设计准则。" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Actions should be simple and easy to understand for agents." }), " 对于 Agent 来说，操作应该简单易懂。许多 bash 命令都有包括数十个选项的文档。只有几个选项的简单命令和简明扼要的文档更便于 Agent 使用，从而减少了演示或微调的需要。"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Actions should be compact and efficient." }), " 操作应简洁高效。重要的操作（如文件导航、编辑）应尽可能合并为较少的操作。高效的操作有助于 Agent 在实现目标的过程中取得有意义的进展。因此，一个糟糕的设计会有许多简单的操作，而这些操作必须在多个回合中进行组合，才能使高阶操作生效。"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Environment feedback should be informative but concise." }), " 环境反馈应信息充足而简洁。高质量的反馈应为 Agent 提供有关当前环境状态（以及 Agent 最近操作的效果）的实质性信息，而不提供不必要的细节。例如，在编辑文件时，向 Agent 提供有关修改内容的最新信息就很有帮助。"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Guardrails mitigate error propagation and hasten recovery." }), " 护栏可减轻错误传播并加快恢复。与人类一样，LM 也会犯错，在编辑或搜索时，他们可能很难从这些错误中恢复过来。建立防护栏（如自动检测错误的代码语法检查器）可以帮助 Agent 识别并快速纠正错误。"] }), "\n"] }), "\n", _jsx(_components.p, { children: "我们看默认 gemini-cli 有哪些工具" }), "\n", _jsx(_components.p, { children: "暂时无法在飞书文档外展示此内容" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "list_directory( ls )" }), "\n", _jsx(_components.li, { children: "read_file" }), "\n", _jsx(_components.li, { children: _jsx(_components.strong, { children: "search_file_content" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.strong, { children: "glob 文件查找" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.strong, { children: "replace (editTool)" }) }), "\n", _jsx(_components.li, { children: "write_file" }), "\n", _jsx(_components.li, { children: "web_fetch" }), "\n", _jsx(_components.li, { children: "read_many_files" }), "\n", _jsx(_components.li, { children: "run_shell_command" }), "\n", _jsx(_components.li, { children: "save_memory" }), "\n", _jsx(_components.li, { children: "google_web_search" }), "\n"] }), "\n", _jsx(_components.p, { children: "是不是感觉和上面论文里的抽象非常相似，尤其我们看论文中提到的 Search 和 Edit" }), "\n", _jsxs(_components.p, { children: ["第一点，", _jsx(_components.strong, { children: "对于 Agent 来说，操作应该简单易懂。对 Agent 开放的参数足够少。" })] }), "\n", _jsxs(_components.p, { children: ["以 grep 为例子，左边是对 agent 开放的参数，右边是 api 的参数。只需要给 Agent 使用最高频最合适最直接的参数即可。如果真有需要再弄的，LLM 会自己用 ", _jsx(_components.code, { children: "run_shell_command" }), " 去执行对应的 command。"] }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "/images/swe-agent/image%20(11).png", alt: "Agent Parameters vs API Parameters" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "/images/swe-agent/image%20(12).png", alt: "Grep Implementation" }) }), "\n", _jsxs(_components.p, { children: ["第二点，", _jsx(_components.strong, { children: "操作应简洁高效。重要的操作（如文件导航、编辑）应尽可能合并为较少的操作。" })] }), "\n", _jsx(_components.p, { children: "Grep 操作是多种 grep 策略的组合（git grep 、system grep、js grep）" }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "/images/swe-agent/image%20(13).png", alt: "Grep Strategy Combination" }) }), "\n", _jsx(_components.p, { children: "Edit 操作更为复杂, 组合了读取文件、创建文件、写入操作的明亮" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-Plain", children: "execute 开始\n ↓\n参数验证 (validateToolParams)\n ↓ (失败则返回错误)\n计算编辑 (calculateEdit)\n ↓ (异常则返回错误)\n检查编辑错误\n ↓ (有错误则返回)\n创建父目录 + 写入文件\n ↓ (写入失败则返回错误)\n构建显示结果 (新文件 vs 差异对比)\n ↓\n构建成功消息\n ↓\n返回结果 { llmContent, returnDisplay }\n" }) }), "\n", _jsxs(_components.p, { children: ["第三点，", _jsx(_components.strong, { children: "环境反馈应信息充足而简洁" }), "。 Gemini-Cli 做了 llm content 和 user display 的区别化 output"] }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "/images/swe-agent/image%20(14).png", alt: "LLM Content vs User Display" }) }), "\n", _jsx(_components.p, { children: "Grep 为例，非常简要的给 LLM 说了关键动作和结果" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-JavaScript", children: "llmContent = `Found ${matchCount} ${matchTerm} for pattern \"${params.pattern}\" in path \"${searchDirDisplay}\"${params.include ? ` (filter: \"${params.include}\")` : ''}:\\n---\\n`;\nreturnDisplay= `Found ${matchCount} ${matchTerm}`\n" }) }), "\n", _jsx(_components.p, { children: "Edit 为例，明确的展示了 Create 和 modified 的 context" }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "/images/swe-agent/image%20(16).png", alt: "Edit Operation Context" }) }), "\n", _jsxs(_components.p, { children: ["第四点，", _jsx(_components.strong, { children: "护栏可减轻错误传播并加快恢复。" })] }), "\n", _jsx(_components.p, { children: "Edit 操作是最容易出问题的， Gemini 是这么做的。" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: "validateToolParams：4 个参数，参数多可能出问题" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsx(_components.li, { children: "检查文件路径是否绝对路径" }), "\n", _jsx(_components.li, { children: "检查文件路径是否在根目录内" }), "\n"] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: "读取出错" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsx(_components.li, { children: "文件不存在" }), "\n", _jsx(_components.li, { children: "父目录不存在" }), "\n"] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: "编辑过程中各种各样的问题" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: "处理一些特殊符号的 gemini 幻觉问题， Unescapes a string that might have been overly escaped by an LLM." }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: "处理 LLM 或者系统过度转译问题（引入 LLM 兜底）" }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "/images/swe-agent/image%20(15).png", alt: "LLM Error Recovery" }) }), "\n"] }), "\n"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-TypeScript", children: "`Context: A process needs to find an exact literal, unique match for a specific text snippet within a file's content. The provided snippet failed to match exactly. This is most likely because it has been overly escaped.\n\nTask: Analyze the provided file content and the problematic target snippet. Identify the segment in the file content that the snippet was *most likely* intended to match. Output the *exact*, literal text of that segment from the file content. Focus *only* on removing extra escape characters and correcting formatting, whitespace, or minor differences to achieve a PERFECT literal match. The output must be the exact literal text as it appears in the file.\n\nProblematic target snippet:\n\\`\\`\\`\n${problematicSnippet}\n\\`\\`\\`\n\nFile Content:\n\\`\\`\\`\n${fileContent}\n\\`\\`\\`\n\nFor example, if the problematic target snippet was \"\\\\\\\\\\\\nconst greeting = \\`Hello \\\\\\\\\\`\\${name}\\\\\\\\\\`\\`;\" and the file content had content that looked like \"\\nconst greeting = \\`Hello ${'\\\\`'}\\${name}${'\\\\`'}\\`;\", then corrected_target_snippet should likely be \"\\nconst greeting = \\`Hello ${'\\\\`'}\\${name}${'\\\\`'}\\`;\" to fix the incorrect escaping to match the original file content.\nIf the differences are only in whitespace or formatting, apply similar whitespace/formatting changes to the corrected_target_snippet.\n\nReturn ONLY the corrected target snippet in the specified JSON format with the key 'corrected_target_snippet'. If no clear, unique match can be found, return an empty string for 'corrected_target_snippet'.`\n" }) }), "\n", _jsxs(_components.ol, { start: "3", children: ["\n", _jsx(_components.li, { children: "old_string 不匹配" }), "\n", _jsx(_components.li, { children: "匹配项数目不正确" }), "\n"] }), "\n"] }), "\n"] }), "\n", _jsx(_components.p, { children: "针对每一种错误都给 LLM 和用户做对应的提示" }), "\n", _jsxs(_components.blockquote, { children: ["\n", _jsx(_components.p, { children: "error.raw 最后会作为 llmContent 抛出作为上下文。" }), "\n"] }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "/images/swe-agent/image%20(17).png", alt: "Error Handling Strategies" }) }), "\n", _jsx(_components.h2, { children: "总结" }), "\n", _jsx(_components.p, { children: "Agent 开发很大一定程度都在做 Context Engineer （over prompt engineer）。" }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "/images/swe-agent/image%20(18).png", alt: "Context Engineering vs Prompt Engineering" }) }), "\n", _jsx(_components.p, { children: "除了上下文工程本身之外，LLM 应用程序还必须：" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "将问题分解为控制流" }), "\n", _jsx(_components.li, { children: "正确合并 context window" }), "\n", _jsx(_components.li, { children: "向合适类型和能力的 LLM 发出申请" }), "\n", _jsx(_components.li, { children: "处理生成验证 UIUX 流程" }), "\n", _jsx(_components.li, { children: "更多 - 护栏、安全、评估 eval、并行性、prefetch......" }), "\n"] }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "/images/swe-agent/image%20(19).png", alt: "Agent Development Framework" }) }), "\n", _jsx(_components.p, { children: "我相信，这篇文章一定对你有所启发，是时候构建一个稳健的 Agent 了。" })] }); } function MDXContent(props = {}) { const {wrapper: MDXLayout} = { ..._provideComponents(), ...props.components }; return MDXLayout ? _jsx(MDXLayout, { ...props, children: _jsx(_createMdxContent, { ...props }) }) : _createMdxContent(props); } return { default: MDXContent };

Oanakiaja