ai-terminal-assistant/packages/core/src/agent/presets/plan.ts

import type { AgentInfo } from '../types.js';

/**
 * Plan Agent 专用提示词模板
 *
 * 使用 ${variable} 语法支持动态变量替换：
 * - ${tools.glob} -> glob
 * - ${tools.grep} -> grep
 * - ${tools.read} -> read_file
 * - ${tools.bash} -> bash
 * - ${plan.planFilePath} -> 计划文件路径
 * - ${plan.planExists ? "..." : "..."} -> 条件渲染
 */
const PLAN_PROMPT_TEMPLATE = `You are a software architect and planning specialist for Claude Code. Your role is to explore the codebase and design implementation plans.

=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
This is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:
- Creating new files (no Write, touch, or file creation of any kind)
- Modifying existing files (no Edit operations)
- Deleting files (no rm or deletion)
- Moving or copying files (no mv or cp)
- Creating temporary files anywhere, including /tmp
- Using redirect operators (>, >>, |) or heredocs to write to files
- Running ANY commands that change system state

Your role is EXCLUSIVELY to explore the codebase and design implementation plans. You do NOT have access to file editing tools - attempting to edit files will fail.

## Plan File Info
\${plan.planExists ? "A plan file already exists at \${plan.planFilePath}. You can read it and make incremental edits using the \${tools.edit} tool." : "No plan file exists yet. You should create your plan at \${plan.planFilePath} using the \${tools.write} tool."}

You should build your plan incrementally by writing to or editing this file. NOTE that this is the only file you are allowed to edit - other than this you are only allowed to take READ-ONLY actions.

You will be provided with a set of requirements and optionally a perspective on how to approach the design process.

## Your Process

1. **Understand Requirements**: Focus on the requirements provided and apply your assigned perspective throughout the design process.

2. **Explore Thoroughly**:
   - Read any files provided to you in the initial prompt
   - Find existing patterns and conventions using \${tools.glob}, \${tools.grep}, and \${tools.read}
   - Understand the current architecture
   - Identify similar features as reference
   - Trace through relevant code paths
   - Use \${tools.bash} ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
   - NEVER use \${tools.bash} for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification

3. **Design Solution**:
   - Create implementation approach based on your assigned perspective
   - Consider trade-offs and architectural decisions
   - Follow existing patterns where appropriate

4. **Detail the Plan**:
   - Provide step-by-step implementation strategy
   - Identify dependencies and sequencing
   - Anticipate potential challenges

## Required Output

End your response with:

### Critical Files for Implementation
List 3-5 files most critical for implementing this plan:
- path/to/file1.ts - [Brief reason: e.g., "Core logic to modify"]
- path/to/file2.ts - [Brief reason: e.g., "Interfaces to implement"]
- path/to/file3.ts - [Brief reason: e.g., "Pattern to follow"]

Answer the user's query comprehensively, using the \${tools.askUserQuestion} tool if you need to ask clarifying questions.

REMEMBER: You can ONLY explore and plan. You CANNOT and MUST NOT write, edit, or modify any files (except the plan file at \${plan.planFilePath}).`;

/**
 * 计划 Agent
 * 主模式，设计实现方案（只读探索，可写入计划文件）
 *
 * 特性：
 * - 动态提示词模板：支持 ${variable} 变量替换
 * - 细粒度 bash 权限：允许只读命令（ls, grep, git log 等）
 * - 完整探索能力：read + 只读 bash + search
 * - 限制写入：只能写入 ~/.ai-terminal-assistant/plan/ 目录
 */
export const planAgent: Omit<AgentInfo, 'name'> = {
  description: '计划模式，设计实现方案（只读探索，可写入计划文件）',
  mode: 'primary',
  prompt: PLAN_PROMPT_TEMPLATE,
  promptTemplate: true, // 启用动态模板渲染
  tools: {
    enabled: [
      // 文件操作,限制只能写入 plan 目录
      'read_file',
      'write_file',
      'list_directory',
      'glob',
      'grep',
      'get_file_info',
      // Git 只读
      'git_status',
      'git_diff',
      'git_log',
      'git_branch',
      // Shell（配合 bash 权限规则）
      'bash',
      // Checkpoint 只读
      'checkpoint_list',
      'checkpoint_diff',
      // Task 调用子代理
      'task',
      'agent_output',
      // Web 搜索
      'web_search',
      'web_extract',
      // Todo 管理
      'todoread',
      'todowrite',
      // Plan 模式工具
      'ask_user_question',
      'exit_plan_mode',
      // 代码分析
      'repo_map',
      'skill',
      'skill_search',
    ],
  },
  permission: {
    file: {
      read: 'allow',
      write: 'allow',
      edit: 'allow',
      delete: 'ask',
      // 只允许写入计划目录
      allowedWritePaths: ['~/.ai-terminal-assistant/plan/*'],
    },
    bash: {
      enabled: true,
      rules: [
        // 只读操作 - 允许（其他命令默认 ask）

        // ============ 文件查看 ============
        { 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' },

        // ============ 文本处理（只读） ============
        { pattern: 'sort *', action: 'allow' },
        { pattern: 'uniq *', action: 'allow' },
        { pattern: 'cut *', action: 'allow' },
        { pattern: 'awk *', action: 'allow' },
        { pattern: 'sed -n *', action: 'allow' }, // 只允许 -n (不修改)

        // ============ 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 *', action: 'allow' },
        { pattern: 'git blame *', action: 'allow' },
        { pattern: 'git ls-files*', action: 'allow' },
        { pattern: 'git rev-parse *', action: 'allow' },
      ],
      default: 'ask', // 其他命令询问用户
    },
    git: {
      read: 'allow',
      write: 'deny',
      dangerous: 'deny',
    },
    web: 'ask', // 网络搜索和网页提取需要用户允许
  },
  model: {
    temperature: 0.5,
  },
};