blade-code 0.0.8 → 0.0.10

package/README.en.md

@@ -21,7 +21,7 @@ English | [简体中文](README.md)
   <tr>
     <td width="50%" valign="top">
       <h3>🤖 Intelligent Conversations</h3>
-      <p>Natural language interactions powered by LLMs with context understanding and multi-turn dialogues</p>
+      <p>Natural language interactions powered by LLMs with context understanding and multi-turn dialogues. Simply run <code>blade "task"</code> to launch the UI and auto-send your first message.</p>
     </td>
     <td width="50%" valign="top">
       <h3>🛠️ Rich Toolset</h3>
@@ -92,6 +92,8 @@ blade
 blade --print "Hello, introduce yourself"
 ```
 
+> On the first run, if no API key is detected, Blade will automatically open an interactive setup wizard in your terminal to collect Provider, Base URL, API Key, and model information before continuing.
+
 ---
 
 ## 🔐 Configure API Keys
@@ -110,20 +112,29 @@ export VOLCENGINE_API_KEY="your-volcengine-api-key"
 export BLADE_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
 ```
 
-### Method 2: Command Line Arguments
+### Method 2: First-Run Setup Wizard (Recommended Experience)
+
+```bash
+blade
+# If no API key is configured, an interactive wizard will guide you through Provider, Base URL, API Key, and model setup.
+```
+
+### Method 3: Command Line Arguments
 
 ```bash
-blade --print "Hello"  # Uses configured API key
+blade --api-key your-api-key --base-url https://api.example.com "Hello"
 ```
 
-### Method 3: Configuration File
+### Method 4: Configuration File
 
 ```bash
-# Copy example config
-cp config.env.example .env
+# User-level configuration
+mkdir -p ~/.blade
+nano ~/.blade/config.json
 
-# Edit .env file with your credentials
-nano .env
+# Project-level configuration
+mkdir -p .blade
+nano .blade/config.json
 ```
 
 ### Get API Keys
@@ -141,25 +152,30 @@ nano .env
 # Interactive mode (default)
 blade
 
-# Direct message (with --print for non-interactive)
-blade --print "What is artificial intelligence?"
+# Direct message (automatically sent once the UI is ready)
+blade "What is artificial intelligence?"
 
 # Code generation
-blade --print "Write a debounce function in JavaScript"
+blade "Write a debounce function in JavaScript"
+
+# Non-interactive quick answer
+blade --print "Summarize the repo in one sentence"
 ```
 
+> Any message passed as `blade "..."` is automatically injected and executed once the interactive UI finishes initializing—no extra keystrokes required.
+
 ### Smart Tool Invocation
 
 Blade Code automatically selects appropriate tools based on your needs:
 
 ```bash
 # File operations
-blade --print "List all TypeScript files in the current directory"
+blade "List all TypeScript files in the current directory"
 
 # Git operations
-blade --print "Show the last 5 commit logs"
+blade "Show the last 5 commit logs"
 
-# Code review
+# Code review (non-interactive example)
 blade --print "Review code quality in src/utils directory"
 ```
 
@@ -167,7 +183,7 @@ blade --print "Review code quality in src/utils directory"
 
 ```bash
 # Create or use named session
-blade --sessionId "project-alpha" "Start new project"
+blade --session-id "project-alpha" "Start new project"
 
 # Continue recent session
 blade --continue
@@ -176,7 +192,7 @@ blade --continue
 blade --resume <conversation-id>
 
 # Fork session (create new session from existing)
-blade --resume <id> --forkSession
+blade --resume <id> --fork-session
 ```
 
 ### Print Mode
@@ -188,23 +204,23 @@ Perfect for piping and scripting:
 blade --print "Generate a README template" > README.md
 
 # Specify output format
-blade --print --outputFormat json "Get project info"
+blade --print --output-format json "Get project info"
 
 # Stream JSON output
-blade --print --outputFormat stream-json "Analyze code"
+blade --print --output-format stream-json "Analyze code"
 ```
 
 ### Input/Output Options
 
 ```bash
 # Read from stdin (stream JSON format)
-cat input.json | blade --inputFormat stream-json --print
+cat input.json | blade --input-format stream-json --print
 
 # Include partial message chunks
-blade --print --includePartialMessages "Generate long text"
+blade --print --include-partial-messages "Generate long text"
 
 # Replay user messages
-blade --replayUserMessages < input.txt
+blade --replay-user-messages < input.txt
 ```
 
 ---
@@ -220,10 +236,10 @@ Model Context Protocol allows integration of external tools and resources:
 blade mcp
 
 # Load MCP config from JSON file
-blade --mcpConfig config.json "Use external tools"
+blade --mcp-config config.json "Use external tools"
 
 # Strict mode (only use specified MCP config)
-blade --mcpConfig config.json --strictMcpConfig "Query"
+blade --mcp-config config.json --strict-mcp-config "Query"
 ```
 
 ### Configuration Management
@@ -249,10 +265,13 @@ blade setup-token
 blade --model qwen-max --print "Complex question"
 
 # Set fallback model
-blade --fallbackModel qwen-turbo --print "Question"
+blade --fallback-model qwen-turbo --print "Question"
 
 # Custom system prompt
-blade --appendSystemPrompt "You are a senior architect" --print "Design microservices architecture"
+blade --append-system-prompt "You are a senior architect" --print "Design microservices architecture"
+
+# Replace default system prompt entirely
+blade --system-prompt "You are a TypeScript expert" --print "Explain decorators"
 
 # Custom agent config
 blade --agents '{"reviewer": {"model": "qwen-max"}}' --print "Review code"
@@ -260,22 +279,22 @@ blade --agents '{"reviewer": {"model": "qwen-max"}}' --print "Review code"
 
 ### Security & Permissions
 
-```bash
-# Skip permission checks (dangerous)
-blade --dangerouslySkipPermissions --print "Execute command"
+Blade ships with a three-tier permission system (`allow` / `ask` / `deny`). You can fine-tune runtime behavior with CLI flags:
 
+```bash
 # Allow specific tools only
-blade --allowedTools "read,write" --print "Handle files"
+blade --allowed-tools "read,write" --print "Handle files"
 
 # Disallow specific tools
-blade --disallowedTools "bash,execute" --print "Safe operations"
+blade --disallowed-tools "bash,execute" --print "Safe operations"
 
 # Permission modes
-blade --permissionMode plan --print "Plan task"  # Plan only, no execution
-blade --permissionMode acceptEdits --print "Modify code"  # Auto-accept edits
+blade --permission-mode plan --print "Plan task"       # Plan only, no execution
+blade --permission-mode autoEdit --print "Modify code" # Auto-approve edits
+blade --yolo --print "Run high-trust operations"       # Approve every tool call
 
 # Add allowed directories
-blade --addDir /path/to/dir --print "Access directory"
+blade --add-dir /path/to/dir --print "Access directory"
 ```
 
 ### IDE Integration
@@ -292,7 +311,7 @@ blade --ide
 blade --settings settings.json
 
 # Specify config sources
-blade --settingSources "global,user,local"
+blade --setting-sources "global,user,local"
 ```
 
 ---
@@ -324,40 +343,41 @@ blade --settingSources "global,user,local"
 | Option | Short | Description |
 |--------|-------|-------------|
 | `--print` | `-p` | Print response and exit (for piping) |
-| `--outputFormat <format>` | | Output format: text/json/stream-json (with --print only) |
-| `--includePartialMessages` | | Include partial message chunks |
+| `--output-format <format>` | | Output format: text/json/stream-json (with --print only) |
+| `--include-partial-messages` | | Include partial message chunks |
 
 ### Input Options
 
 | Option | Description |
 |--------|-------------|
-| `--inputFormat <format>` | Input format: text/stream-json |
-| `--replayUserMessages` | Re-emit user messages from stdin |
+| `--input-format <format>` | Input format: text/stream-json |
+| `--replay-user-messages` | Re-emit user messages from stdin |
 
 ### Security Options
 
 | Option | Description |
 |--------|-------------|
-| `--dangerouslySkipPermissions` | Skip all permission checks (dangerous) |
-| `--allowedTools <tools>` | Allowed tools list (comma or space separated) |
-| `--disallowedTools <tools>` | Disallowed tools list (comma or space separated) |
-| `--permissionMode <mode>` | Permission mode: acceptEdits/bypassPermissions/default/plan |
-| `--addDir <dirs>` | Additional directories for tool access |
+| `--allowed-tools <tools>` | Allowed tools list (comma or space separated) |
+| `--disallowed-tools <tools>` | Disallowed tools list (comma or space separated) |
+| `--permission-mode <mode>` | Permission mode: default/autoEdit/yolo/plan |
+| `--yolo` | Shortcut for `--permission-mode yolo` |
+| `--add-dir <dirs>` | Additional directories for tool access |
 
 ### MCP Options
 
 | Option | Description |
 |--------|-------------|
-| `--mcpConfig <files>` | Load MCP servers from JSON files or strings |
-| `--strictMcpConfig` | Only use servers from --mcpConfig |
+| `--mcp-config <files>` | Load MCP servers from JSON files or strings |
+| `--strict-mcp-config` | Only use servers from --mcp-config |
 
 ### AI Options
 
 | Option | Description |
 |--------|-------------|
-| `--appendSystemPrompt <text>` | Append system prompt to default |
+| `--append-system-prompt <text>` | Append system prompt to default |
+| `--system-prompt <text>` | Replace default system prompt |
 | `--model <name>` | Model for current session |
-| `--fallbackModel <name>` | Enable automatic fallback to specified model |
+| `--fallback-model <name>` | Enable automatic fallback to specified model |
 | `--agents <json>` | Custom agent configuration JSON |
 
 ### Session Options
@@ -366,15 +386,15 @@ blade --settingSources "global,user,local"
 |--------|-------|-------------|
 | `--continue` | `-c` | Continue recent session |
 | `--resume <id>` | `-r` | Resume specific session |
-| `--forkSession` | | Create new session ID when resuming |
-| `--sessionId <id>` | | Use specific session ID |
+| `--fork-session` | | Create new session ID when resuming |
+| `--session-id <id>` | | Use specific session ID |
 
 ### Configuration Options
 
 | Option | Description |
 |--------|-------------|
 | `--settings <path>` | Settings JSON file path or JSON string |
-| `--settingSources <sources>` | Setting sources to load (comma separated) |
+| `--setting-sources <sources>` | Setting sources to load (comma separated) |
 
 ### Integration Options
 

package/README.md

@@ -21,7 +21,7 @@
   <tr>
     <td width="50%" valign="top">
       <h3>🤖 智能对话</h3>
-      <p>基于大语言模型的自然语言交互，支持上下文理解和多轮对话</p>
+      <p>基于大语言模型的自然语言交互，支持上下文理解和多轮对话，直接运行 <code>blade "任务"</code> 即可自动进入界面并发送首条消息</p>
     </td>
     <td width="50%" valign="top">
       <h3>🛠️ 丰富工具</h3>
@@ -52,6 +52,15 @@
 
 ---
 
+## 📖 文档
+
+- **[完整文档](docs/index.md)** - 文档中心导航
+- **[用户文档](docs/public/README.md)** - 安装、配置、使用指南
+- **[开发者文档](docs/development/README.md)** - 架构设计、技术实现
+- **[贡献指南](docs/contributing/README.md)** - 参与开源贡献
+
+---
+
 ## 🚀 快速开始
 
 ### ⚡ 零安装试用
@@ -92,6 +101,8 @@ blade
 blade --print "你好，介绍一下自己"
 ```
 
+> 首次运行若未检测到 API 密钥，会自动弹出终端设置向导，按提示填写 Provider / Base URL / API Key / 模型后即可继续使用。
+
 ---
 
 ## 🔐 配置 API 密钥
@@ -110,20 +121,31 @@ export VOLCENGINE_API_KEY="your-volcengine-api-key"
 export BLADE_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
 ```
 
-### 方式二：命令行参数
+### 方式二：首启设置向导（推荐体验）
 
 ```bash
-blade --api-key your-api-key --base-url https://api.example.com "你好"
+blade
+# 若未配置 API Key，将自动引导完成 Provider、Base URL、API Key、模型的填写
 ```
 
-### 方式三：配置文件
+### 方式三：命令行参数
 
 ```bash
-# 复制示例配置文件
-cp config.env.example .env
+blade --api-key your-api-key --base-url https://api.example.com "你好"
+```
 
-# 编辑 .env 文件，填入您的配置
-nano .env
+### 方式四：配置文件
+
+```bash
+# 用户级配置
+mkdir -p ~/.blade
+nano ~/.blade/config.json
+
+# 项目级配置（提交到仓库）
+mkdir -p .blade
+nano .blade/config.json
+# 或者为当前机器准备不提交的设置
+nano .blade/settings.local.json
 ```
 
 ### 获取 API 密钥
@@ -141,7 +163,7 @@ nano .env
 # 交互式模式（默认）
 blade
 
-# 直接发送消息
+# 直接发送消息（会在 UI 初始化后自动输入并执行）
 blade "什么是人工智能？"
 
 # 代码生成
@@ -167,7 +189,7 @@ blade "审查 src/utils 目录的代码质量"
 
 ```bash
 # 创建或使用命名会话
-blade --sessionId "project-alpha" "开始新项目"
+blade --session-id "project-alpha" "开始新项目"
 
 # 继续最近的会话
 blade --continue
@@ -176,7 +198,7 @@ blade --continue
 blade --resume <conversation-id>
 
 # Fork 会话（从现有会话创建新会话）
-blade --resume <id> --forkSession
+blade --resume <id> --fork-session
 ```
 
 ### 打印模式
@@ -188,23 +210,23 @@ blade --resume <id> --forkSession
 blade --print "生成一个 README 模板" > README.md
 
 # 指定输出格式
-blade --print --outputFormat json "获取项目信息"
+blade --print --output-format json "获取项目信息"
 
 # 流式 JSON 输出
-blade --print --outputFormat stream-json "分析代码"
+blade --print --output-format stream-json "分析代码"
 ```
 
 ### 输入/输出选项
 
 ```bash
 # 从标准输入读取（流式 JSON 格式）
-cat input.json | blade --inputFormat stream-json --print
+cat input.json | blade --input-format stream-json --print
 
 # 包含部分消息块
-blade --print --includePartialMessages "长文本生成"
+blade --print --include-partial-messages "长文本生成"
 
 # 重新发送用户消息
-blade --replayUserMessages < input.txt
+blade --replay-user-messages < input.txt
 ```
 
 ---
@@ -220,10 +242,10 @@ Model Context Protocol 允许集成外部工具和资源：
 blade mcp
 
 # 从 JSON 文件加载 MCP 配置
-blade --mcpConfig config.json "使用外部工具"
+blade --mcp-config config.json "使用外部工具"
 
 # 仅使用指定的 MCP 配置（严格模式）
-blade --mcpConfig config.json --strictMcpConfig "查询"
+blade --mcp-config config.json --strict-mcp-config "查询"
 ```
 
 ### 配置管理
@@ -249,10 +271,13 @@ blade setup-token
 blade --model qwen-max "复杂的问题"
 
 # 设置回退模型
-blade --fallbackModel qwen-turbo "问题"
+blade --fallback-model qwen-turbo "问题"
 
 # 自定义系统提示
-blade --appendSystemPrompt "你是一位资深架构师" "设计微服务架构"
+blade --append-system-prompt "你是一位资深架构师" "设计微服务架构"
+
+# 完全替换默认系统提示
+blade --system-prompt "你是一位 TypeScript 专家" "解释装饰器"
 
 # 自定义 Agent 配置
 blade --agents '{"reviewer": {"model": "qwen-max"}}' "审查代码"
@@ -260,24 +285,48 @@ blade --agents '{"reviewer": {"model": "qwen-max"}}' "审查代码"
 
 ### 安全与权限
 
-```bash
-# 跳过权限检查（危险）
-blade --dangerouslySkipPermissions "执行命令"
+Blade 提供强大的三级权限控制系统（allow/ask/deny）：
 
+```bash
 # 仅允许特定工具
-blade --allowedTools "read,write" "处理文件"
+blade --allowed-tools "read,write" "处理文件"
 
 # 禁止特定工具
-blade --disallowedTools "bash,execute" "安全操作"
+blade --disallowed-tools "bash,execute" "安全操作"
 
 # 权限模式
-blade --permissionMode plan "规划任务"  # 仅规划不执行
-blade --permissionMode acceptEdits "修改代码"  # 自动接受编辑
+blade --permission-mode plan "规划任务"      # 仅规划不执行
+blade --permission-mode autoEdit "修改代码"   # 自动接受编辑
+blade --yolo "任意工具自动批准"              # 开启 YOLO 模式
 
 # 添加允许访问的目录
-blade --addDir /path/to/dir "访问目录"
+blade --add-dir /path/to/dir "访问目录"
+```
+
+**权限配置示例** (`.blade/settings.json`):
+```json
+{
+  "permissions": {
+    "allow": [
+      "Read(file_path:**/*.ts)",
+      "Grep",
+      "Glob"
+    ],
+    "ask": [
+      "Write",
+      "Edit",
+      "Bash(command:npm *)"
+    ],
+    "deny": [
+      "Read(file_path:.env)",
+      "Bash(command:rm -rf *)"
+    ]
+  }
+}
 ```
 
+详见 [权限系统指南](docs/public/configuration/permissions.md)
+
 ### IDE 集成
 
 ```bash
@@ -292,7 +341,7 @@ blade --ide
 blade --settings settings.json
 
 # 指定配置源
-blade --settingSources "global,user,local"
+blade --setting-sources "global,user,local"
 ```
 
 ---
@@ -324,40 +373,41 @@ blade --settingSources "global,user,local"
 | 选项 | 简写 | 说明 |
 |------|------|------|
 | `--print` | `-p` | 打印响应并退出（适合管道） |
-| `--outputFormat <format>` | | 输出格式：text/json/stream-json（仅与 --print 配合） |
-| `--includePartialMessages` | | 包含部分消息块 |
+| `--output-format <format>` | | 输出格式：text/json/stream-json（仅与 --print 配合） |
+| `--include-partial-messages` | | 包含部分消息块 |
 
 ### 输入选项
 
 | 选项 | 说明 |
 |------|------|
-| `--inputFormat <format>` | 输入格式：text/stream-json |
-| `--replayUserMessages` | 重新发送来自 stdin 的用户消息 |
+| `--input-format <format>` | 输入格式：text/stream-json |
+| `--replay-user-messages` | 重新发送来自 stdin 的用户消息 |
 
 ### 安全选项
 
 | 选项 | 说明 |
 |------|------|
-| `--dangerouslySkipPermissions` | 跳过所有权限检查（危险） |
-| `--allowedTools <tools>` | 允许的工具列表（逗号或空格分隔） |
-| `--disallowedTools <tools>` | 禁止的工具列表（逗号或空格分隔） |
-| `--permissionMode <mode>` | 权限模式：acceptEdits/bypassPermissions/default/plan |
-| `--addDir <dirs>` | 允许工具访问的额外目录 |
+| `--allowed-tools <tools>` | 允许的工具列表（逗号或空格分隔） |
+| `--disallowed-tools <tools>` | 禁止的工具列表（逗号或空格分隔） |
+| `--permission-mode <mode>` | 权限模式：default/autoEdit/yolo/plan |
+| `--yolo` | YOLO 模式快捷开关（等同于 `--permission-mode yolo`） |
+| `--add-dir <dirs>` | 允许工具访问的额外目录 |
 
 ### MCP 选项
 
 | 选项 | 说明 |
 |------|------|
-| `--mcpConfig <files>` | 从 JSON 文件或字符串加载 MCP 服务器 |
-| `--strictMcpConfig` | 仅使用 --mcpConfig 指定的服务器 |
+| `--mcp-config <files>` | 从 JSON 文件或字符串加载 MCP 服务器 |
+| `--strict-mcp-config` | 仅使用 --mcp-config 指定的服务器 |
 
 ### AI 选项
 
 | 选项 | 说明 |
 |------|------|
-| `--appendSystemPrompt <text>` | 追加系统提示到默认提示 |
+| `--append-system-prompt <text>` | 追加系统提示到默认提示 |
+| `--system-prompt <text>` | 完全替换默认系统提示 |
 | `--model <name>` | 当前会话使用的模型 |
-| `--fallbackModel <name>` | 启用自动回退到指定模型 |
+| `--fallback-model <name>` | 启用自动回退到指定模型 |
 | `--agents <json>` | 自定义 Agent 的 JSON 对象 |
 
 ### 会话选项
@@ -366,15 +416,15 @@ blade --settingSources "global,user,local"
 |------|------|------|
 | `--continue` | `-c` | 继续最近的会话 |
 | `--resume <id>` | `-r` | 恢复指定会话 |
-| `--forkSession` | | 恢复会话时创建新会话 ID |
-| `--sessionId <id>` | | 使用特定会话 ID |
+| `--fork-session` | | 恢复会话时创建新会话 ID |
+| `--session-id <id>` | | 使用特定会话 ID |
 
 ### 配置选项
 
 | 选项 | 说明 |
 |------|------|
 | `--settings <path>` | | 设置 JSON 文件路径或 JSON 字符串 |
-| `--settingSources <sources>` | | 要加载的设置源（逗号分隔） |
+| `--setting-sources <sources>` | | 要加载的设置源（逗号分隔） |
 
 ### 集成选项
 
@@ -397,13 +447,19 @@ Blade Code 采用现代化的扁平化架构设计：
 
 ```
 src/
-├── agent/          # Agent 核心逻辑
+├── agent/          # Agent 核心逻辑和控制器
 ├── cli/            # CLI 配置和中间件
-├── commands/       # 命令处理器
-├── config/         # 配置管理
-├── tools/          # 工具系统
-├── ui/             # UI 组件（基于 Ink）
-├── services/       # 共享服务
+├── commands/       # CLI 命令定义和处理
+├── config/         # 统一配置管理（双文件系统）
+├── tools/          # 工具系统（含执行管道）
+│   ├── builtin/    # 内置工具
+│   ├── execution/  # 6阶段执行管道
+│   ├── registry/   # 工具注册中心
+│   └── validation/ # 参数验证
+├── ui/             # UI 组件和界面（基于 Ink）
+├── services/       # 共享服务层
+├── prompts/        # 提示模板管理
+├── mcp/            # MCP 协议实现
 └── utils/          # 工具函数
 ```
 
@@ -414,6 +470,9 @@ src/
 - 🎨 **React for CLI**：基于 Ink 的现代化 UI
 - 🔧 **TypeScript**：完整类型支持
 - ✅ **全面测试**：单元、集成、E2E 测试覆盖
+- 🔒 **6阶段执行管道**：Discovery → Validation → Permission → Confirmation → Execution → Formatting
+- 🛡️ **三级权限控制**：allow/ask/deny 精细化权限管理
+- 🎯 **双配置文件系统**：config.json（基础配置） + settings.json（行为配置）
 
 ---