diff --git a/packages/core/src/agent/presets/build.ts b/packages/core/src/agent/presets/build.ts index 378060b..38d755f 100644 --- a/packages/core/src/agent/presets/build.ts +++ b/packages/core/src/agent/presets/build.ts @@ -1,7 +1,20 @@ import type { AgentInfo } from '../types.js'; /** - * Build Agent 默认提示词 + * Build Agent 默认提示词模板 + * + * 使用 ${variable} 语法支持动态变量替换: + * - ${tools.bash} -> bash + * - ${tools.read} -> read_file + * - ${tools.edit} -> edit_file + * - ${tools.write} -> write_file + * - ${tools.glob} -> glob + * - ${tools.grep} -> grep + * - ${tools.task} -> task + * - ${tools.todoWrite} -> todowrite + * - ${tools.askUserQuestion} -> ask_user_question + * - ${tools.webExtract} -> web_extract + * - ${tools.explore} -> Explore (subagent type) */ const BUILD_PROMPT = `You are an interactive CLI tool that helps users with software engineering tasks. Use the instructions below and the tools available to you to assist the user. @@ -122,9 +135,172 @@ assistant: [Uses the \${TASK_TOOL_NAME} tool with subagent_type=\${EXPLORE_SUBAG /** * 构建 Agent * 主模式,拥有完整权限执行编码任务 + * + * 特性: + * - 动态提示词模板:支持 ${variable} 变量替换 + * - 完整文件读写权限 + * - 完整 bash 权限(询问用户确认) + * - 完整 Git 权限(危险操作需确认) + * - 支持 Task 子代理调用 + * - Todo 任务管理 + * - Web 搜索和提取 + * - Checkpoint 管理 */ export const buildAgent: Omit = { description: '构建模式,拥有完整权限执行编码任务', mode: 'primary', prompt: BUILD_PROMPT, + promptTemplate: true, // 启用动态模板渲染 + tools: { + enabled: [ + // ============ 文件系统操作 ============ + 'read_file', + 'write_file', + 'edit_file', + 'multi_edit', + 'list_directory', + 'create_directory', + 'search_files', + 'glob', + 'grep', + 'get_file_info', + 'move_file', + 'copy_file', + 'delete_file', + + // ============ Shell ============ + 'bash', + + // ============ Git 完整操作 ============ + 'git_status', + 'git_diff', + 'git_log', + 'git_branch', + 'git_add', + 'git_commit', + 'git_push', + 'git_pull', + 'git_checkout', + 'git_stash', + + // ============ Task 子代理 ============ + 'task', + 'agent_output', + + // ============ Todo 任务管理 ============ + 'todoread', + 'todowrite', + + // ============ Web 工具 ============ + 'web_search', + 'web_extract', + + // ============ Checkpoint 管理 ============ + 'checkpoint_create', + 'checkpoint_list', + 'checkpoint_diff', + 'checkpoint_restore', + 'undo', + + // ============ 代码分析 ============ + 'repo_map', + + // ============ Plan 模式工具 ============ + 'ask_user_question', + 'enter_plan_mode', + + // ============ Skill 工具 ============ + 'skill', + 'skill_search', + + // ============ 工具搜索 ============ + 'tool_search', + ], + }, + permission: { + file: { + read: 'allow', + write: 'ask', + edit: 'ask', + delete: 'ask', + }, + bash: { + enabled: true, + rules: [ + // ============ 常用只读操作 - 允许 ============ + { pattern: 'ls', action: 'allow' }, + { pattern: 'ls *', action: 'allow' }, + { pattern: 'pwd', action: 'allow' }, + { pattern: 'cat *', action: 'allow' }, + { pattern: 'head *', action: 'allow' }, + { pattern: 'tail *', action: 'allow' }, + { pattern: 'less *', action: 'allow' }, + { pattern: 'more *', action: 'allow' }, + + // ============ 搜索 - 允许 ============ + { pattern: 'find *', action: 'allow' }, + { pattern: 'grep *', action: 'allow' }, + { pattern: 'rg *', action: 'allow' }, + { pattern: 'tree', action: 'allow' }, + { pattern: 'tree *', action: 'allow' }, + + // ============ 文件信息 - 允许 ============ + { pattern: 'wc *', action: 'allow' }, + { pattern: 'stat *', action: 'allow' }, + { pattern: 'file *', action: 'allow' }, + { pattern: 'du *', action: 'allow' }, + { pattern: 'diff *', action: 'allow' }, + { pattern: 'which *', action: 'allow' }, + { pattern: 'whereis *', action: 'allow' }, + + // ============ Git 只读 - 允许 ============ + { pattern: 'git status', action: 'allow' }, + { pattern: 'git status *', action: 'allow' }, + { pattern: 'git diff', action: 'allow' }, + { pattern: 'git diff *', action: 'allow' }, + { pattern: 'git log', action: 'allow' }, + { pattern: 'git log *', action: 'allow' }, + { pattern: 'git show *', action: 'allow' }, + { pattern: 'git branch', action: 'allow' }, + { pattern: 'git branch -v*', action: 'allow' }, + { pattern: 'git branch -a*', action: 'allow' }, + { pattern: 'git branch --list*', action: 'allow' }, + { pattern: 'git remote -v', action: 'allow' }, + { pattern: 'git tag', action: 'allow' }, + { pattern: 'git tag -l*', action: 'allow' }, + { pattern: 'git blame *', action: 'allow' }, + { pattern: 'git ls-files*', action: 'allow' }, + { pattern: 'git rev-parse *', action: 'allow' }, + + // ============ 开发工具只读 - 允许 ============ + { pattern: 'node --version', action: 'allow' }, + { pattern: 'npm --version', action: 'allow' }, + { pattern: 'pnpm --version', action: 'allow' }, + { pattern: 'bun --version', action: 'allow' }, + { pattern: 'yarn --version', action: 'allow' }, + { pattern: 'python --version', action: 'allow' }, + { pattern: 'python3 --version', action: 'allow' }, + { pattern: 'go version', action: 'allow' }, + { pattern: 'rustc --version', action: 'allow' }, + { pattern: 'cargo --version', action: 'allow' }, + + // ============ 危险操作 - 拒绝 ============ + { pattern: 'rm -rf /*', action: 'ask' }, + { pattern: 'rm -rf /', action: 'ask' }, + { pattern: 'sudo *', action: 'ask' }, + { pattern: 'chmod 777 *', action: 'ask' }, + { pattern: '* | sudo *', action: 'ask' }, + { pattern: 'git push --force*', action: 'ask' }, + { pattern: 'git push -f*', action: 'ask' }, + { pattern: 'git reset --hard*', action: 'ask' }, + ], + default: 'ask', // 其他命令询问用户 + }, + git: { + read: 'allow', + write: 'ask', + dangerous: 'ask', + }, + web: 'ask', + }, }; diff --git a/packages/core/src/tools/descriptions/plan/enter_plan_mode.txt b/packages/core/src/tools/descriptions/plan/enter_plan_mode.txt new file mode 100644 index 0000000..72c8533 --- /dev/null +++ b/packages/core/src/tools/descriptions/plan/enter_plan_mode.txt @@ -0,0 +1,85 @@ +Use this tool proactively when you're about to start a non-trivial implementation task. Getting user sign-off on your approach before writing code prevents wasted effort and ensures alignment. This tool transitions you into plan mode where you can explore the codebase and design an implementation approach for user approval. + +## When to Use This Tool + +**Prefer using EnterPlanMode** for implementation tasks unless they're simple. Use it when ANY of these conditions apply: + +1. **New Feature Implementation**: Adding meaningful new functionality + - Example: "Add a logout button" - where should it go? What should happen on click? + - Example: "Add form validation" - what rules? What error messages? + +2. **Multiple Valid Approaches**: The task can be solved in several different ways + - Example: "Add caching to the API" - could use Redis, in-memory, file-based, etc. + - Example: "Improve performance" - many optimization strategies possible + +3. **Code Modifications**: Changes that affect existing behavior or structure + - Example: "Update the login flow" - what exactly should change? + - Example: "Refactor this component" - what's the target architecture? + +4. **Architectural Decisions**: The task requires choosing between patterns or technologies + - Example: "Add real-time updates" - WebSockets vs SSE vs polling + - Example: "Implement state management" - Redux vs Context vs custom solution + +5. **Multi-File Changes**: The task will likely touch more than 2-3 files + - Example: "Refactor the authentication system" + - Example: "Add a new API endpoint with tests" + +6. **Unclear Requirements**: You need to explore before understanding the full scope + - Example: "Make the app faster" - need to profile and identify bottlenecks + - Example: "Fix the bug in checkout" - need to investigate root cause + +7. **User Preferences Matter**: The implementation could reasonably go multiple ways + - If you would use ${ASK_USER_QUESTION_TOOL_NAME} to clarify the approach, use EnterPlanMode instead + - Plan mode lets you explore first, then present options with context + +## When NOT to Use This Tool + +Only skip EnterPlanMode for simple tasks: +- Single-line or few-line fixes (typos, obvious bugs, small tweaks) +- Adding a single function with clear requirements +- Tasks where the user has given very specific, detailed instructions +- Pure research/exploration tasks (use the Task tool with explore agent instead) + +## What Happens in Plan Mode + +In plan mode, you'll: +1. Thoroughly explore the codebase using Glob, Grep, and Read tools +2. Understand existing patterns and architecture +3. Design an implementation approach +4. Present your plan to the user for approval +5. Use ${ASK_USER_QUESTION_TOOL_NAME} if you need to clarify approaches +6. Exit plan mode with ExitPlanMode when ready to implement + +## Examples + +### GOOD - Use EnterPlanMode: +User: "Add user authentication to the app" +- Requires architectural decisions (session vs JWT, where to store tokens, middleware structure) + +User: "Optimize the database queries" +- Multiple approaches possible, need to profile first, significant impact + +User: "Implement dark mode" +- Architectural decision on theme system, affects many components + +User: "Add a delete button to the user profile" +- Seems simple but involves: where to place it, confirmation dialog, API call, error handling, state updates + +User: "Update the error handling in the API" +- Affects multiple files, user should approve the approach + +### BAD - Don't use EnterPlanMode: +User: "Fix the typo in the README" +- Straightforward, no planning needed + +User: "Add a console.log to debug this function" +- Simple, obvious implementation + +User: "What files handle routing?" +- Research task, not implementation planning + +## Important Notes + +- This tool REQUIRES user approval - they must consent to entering plan mode +- If unsure whether to use it, err on the side of planning - it's better to get alignment upfront than to redo work +- Users appreciate being consulted before significant changes are made to their codebase diff --git a/packages/core/src/tools/descriptions/plan/exit_plan_mode.txt b/packages/core/src/tools/descriptions/plan/exit_plan_mode.txt new file mode 100644 index 0000000..ac83c2f --- /dev/null +++ b/packages/core/src/tools/descriptions/plan/exit_plan_mode.txt @@ -0,0 +1,24 @@ +Use this tool when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval. + +## How This Tool Works +- You should have already written your plan to the plan file specified in the plan mode system message +- This tool does NOT take the plan content as a parameter - it will read the plan from the file you wrote +- This tool simply signals that you're done planning and ready for the user to review and approve +- The user will see the contents of your plan file when they review it + +## When to Use This Tool +IMPORTANT: Only use this tool when the task requires planning the implementation steps of a task that requires writing code. For research tasks where you're gathering information, searching files, reading files or in general trying to understand the codebase - do NOT use this tool. + +## Handling Ambiguity in Plans +Before using this tool, ensure your plan is clear and unambiguous. If there are multiple valid approaches or unclear requirements: +1. Use the ${ASK_USER_QUESTION_TOOL_NAME} tool to clarify with the user +2. Ask about specific implementation choices (e.g., architectural patterns, which library to use) +3. Clarify any assumptions that could affect the implementation +4. Edit your plan file to incorporate user feedback +5. Only proceed with ExitPlanMode after resolving ambiguities and updating the plan file + +## Examples + +1. Initial task: "Search for and understand the implementation of vim mode in the codebase" - Do not use the exit plan mode tool because you are not planning the implementation steps of a task. +2. Initial task: "Help me implement yank mode for vim" - Use the exit plan mode tool after you have finished planning the implementation steps of the task. +3. Initial task: "Add a new feature to handle user authentication" - If unsure about auth method (OAuth, JWT, etc.), use ${ASK_USER_QUESTION_TOOL_NAME} first, then use exit plan mode tool after clarifying the approach. diff --git a/packages/core/src/tools/load_description.ts b/packages/core/src/tools/load_description.ts index 0334bb2..1250946 100644 --- a/packages/core/src/tools/load_description.ts +++ b/packages/core/src/tools/load_description.ts @@ -42,6 +42,8 @@ const TOOL_CATEGORY_MAP: Record = { todo_write: 'todo', // plan ask_user_question: 'plan', + enter_plan_mode: 'plan', + exit_plan_mode: 'plan', // task task: 'task', agent_output: 'task', diff --git a/packages/core/src/tools/plan/enter_plan_mode.ts b/packages/core/src/tools/plan/enter_plan_mode.ts index be714bd..c230f06 100644 --- a/packages/core/src/tools/plan/enter_plan_mode.ts +++ b/packages/core/src/tools/plan/enter_plan_mode.ts @@ -22,36 +22,14 @@ import type { ToolWithMetadata } from '../types.js'; import type { ToolResult } from '../../types/index.js'; +import { loadDescription } from '../load_description.js'; /** * Enter Plan Mode 工具 */ export const enterPlanModeTool: ToolWithMetadata = { name: 'enter_plan_mode', - description: `进入计划模式,在开始非平凡的实现任务前主动使用。 - -使用场景: -- 新功能实现:如 "添加登出按钮"、"实现用户认证" -- 多种可行方案:如 "给 API 添加缓存"(Redis/内存/文件) -- 代码修改:如 "更新登录流程"、"重构组件" -- 架构决策:如 "添加实时更新功能"(WebSocket/SSE/轮询) -- 多文件变更:如 "重构认证系统" -- 需求不明确:如 "让应用更快"、"修复 checkout 的 bug" - -何时不使用: -- 单行修复(错别字、明显 bug、小调整) -- 用户给出了非常具体详细的指令 -- 纯研究/探索任务(使用 Task 工具的 explore agent) - -计划模式中的限制: -进入后只能使用只读工具: -✅ read_file, list_directory, search_files, grep -✅ web_search, web_extract -✅ task(探索代理) -✅ ask_user_question -❌ write_file, edit_file, bash(执行命令) - -完成计划后使用 exit_plan_mode 退出并提交方案供用户审批。`, + description: loadDescription('enter_plan_mode'), metadata: { name: 'enter_plan_mode', diff --git a/packages/core/src/tools/plan/exit_plan_mode.ts b/packages/core/src/tools/plan/exit_plan_mode.ts index 762b2d4..8c77768 100644 --- a/packages/core/src/tools/plan/exit_plan_mode.ts +++ b/packages/core/src/tools/plan/exit_plan_mode.ts @@ -16,6 +16,7 @@ import type { ToolWithMetadata } from '../types.js'; import type { ToolResult } from '../../types/index.js'; +import { loadDescription } from '../load_description.js'; /** * 工具参数 @@ -32,30 +33,7 @@ export interface ExitPlanModeParams { */ export const exitPlanModeTool: ToolWithMetadata = { name: 'exit_plan_mode', - description: `退出计划模式,将方案提交给用户审批。 - -使用条件(调用前必须满足): -1. 已完成方案设计 -2. 计划清晰无歧义 -3. 如有多种方案或不明确的需求,先用 ask_user_question 澄清 - -何时使用: -- 当任务需要规划实现步骤并编写代码时使用 -- 纯研究/探索任务不要使用此工具 - -参数说明: -- launchSwarm (可选): 是否启动多代理协作来实施方案 -- teammateCount (可选): 协作代理的数量(需要 launchSwarm=true) - -示例: -1. 简单退出(用户手动执行): - exit_plan_mode({}) - -2. 启动 swarm 协作实施: - exit_plan_mode({ - launchSwarm: true, - teammateCount: 3 - })`, + description: loadDescription('exit_plan_mode'), metadata: { name: 'exit_plan_mode',