Skip to content

Commit d01d7d5

Browse files
hqwlkjhqwlkj
committed
Merge branch 'main' into refactor/vscode
2 parents 807879b + c505087 commit d01d7d5

14 files changed

Lines changed: 827 additions & 29 deletions

‎.deepcode/AGENTS.md‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ packages/
2525
│ ├── ui/hooks/ # Custom hooks (cursor, history navigation, paste handling, terminal input, statusline)
2626
│ ├── ui/contexts/ # React contexts (AppContext, RawModeContext)
2727
│ ├── ui/statusline/ # Pluggable statusline providers (command, module)
28+
│ ├── ui/utils/ # Shared UI utilities (writing, formatting)
2829
│ └── tests/ # UI-focused tests with run-tests.mjs runner
2930
├── vscode-ide-companion/ # VSCode extension companion
3031
│ └── src/ # extension.ts, provider.ts, utils.ts
@@ -55,6 +56,9 @@ All commands run from the repo root.
5556
| `npm run start` | Runs the locally built CLI (`scripts/start.js`) |
5657
| `npm run build-and-start` | Builds then starts the CLI |
5758
| `npm run clean` | Removes generated files and dist directories |
59+
| `npm run release:version` | Bumps version across all packages |
60+
| `npm run prepare:package` | Prepares the CLI package for distribution |
61+
| `npm run prepare:vscode` | Prepares the VSCode extension for distribution |
5862

5963
To run a **single test file** within a package:
6064
```
@@ -111,17 +115,19 @@ Run the CLI locally for manual testing: `node packages/cli/dist/cli.js` (after `
111115

112116
## Architecture Overview
113117

114-
The CLI (`@vegamo/deepcode-cli`) renders a terminal UI using [Ink](https://github.com/vadimdemedes/ink) (React for terminals). `SessionManager` (in `@vegamo/deepcode-core`) drives the LLM interaction loop: it builds system prompts, sends user messages with optional skills/images, streams responses, executes tool calls via `ToolExecutor`, and compacts context when token thresholds are exceeded (512K for DeepSeek V4 models, 128K for others). OpenAI client connectivity is managed by `createOpenAIClient()` with a 180-second keep-alive timeout.
118+
The CLI (`@vegamo/deepcode-cli`) renders a terminal UI using [Ink](https://github.com/vadimdemedes/ink) (React for terminals). `SessionManager` (in `@vegamo/deepcode-core`) drives the LLM interaction loop: it builds system prompts, sends user messages with optional skills/images, streams responses, executes tool calls via `ToolExecutor`, and compacts context when token thresholds are exceeded (512K for DeepSeek V4 models, 128K for others). OpenAI client connectivity is managed by `createOpenAIClient()` with a 180-second keep-alive timeout. API errors are normalized through `describeLlmError()` in `packages/core/src/common/llm-error.ts`, which produces credential-safe, structured error details.
115119

116-
Seven built-in tools are available to the LLM: `bash`, `read`, `write`, `edit`, `AskUserQuestion`, `UpdatePlan`, and `WebSearch`. Tool definitions are registered in `packages/core/src/tools/executor.ts` and described to the LLM via `packages/core/src/prompt.ts`.
120+
Seven built-in tools are available to the LLM: `bash`, `read`, `write`, `edit`, `AskUserQuestion`, `UpdatePlan`, and `WebSearch`. The `read` tool returns a `snippet_id` that must be passed to subsequent `edit` calls, ensuring edits always operate on a known, session-local file snapshot. Tool definitions are registered in `packages/core/src/tools/executor.ts` and described to the LLM via `packages/core/src/prompt.ts`.
117121

118122
A **permission system** (`packages/core/src/common/permissions.ts`) controls tool execution scopes (read/write/delete/network/git-log, etc.) with configurable allow/deny/ask decisions.
119123

120124
A **file history system** (`packages/core/src/common/file-history.ts`) provides undo/checkpoint support via lightweight Git branches.
121125

122-
**Slash commands**: `/skills`, `/model`, `/new`, `/init`, `/resume`, `/continue`, `/undo`, `/mcp`, `/raw`, `/exit`, plus dynamic `/skill-name` for each loaded skill.
126+
**Slash commands**: `/skills`, `/model`, `/plan`, `/new`, `/init`, `/resume`, `/continue`, `/undo`, `/mcp`, `/raw`, `/exit`, plus dynamic `/skill-name` for each loaded skill.
123127

124-
**Key UI features**: `@` file mentions in the prompt input, `Ctrl+O` to view live process stdout, `Ctrl+V` to paste images, `Ctrl+X` to clear images, Shift+Enter for newlines, pluggable statusline, MCP server status display, undo selector, and permission prompts.
128+
**Plan Mode** (`/plan` or `Shift+Tab`): Restricts the agent to read-only operations on the first turn and requires it to produce a task plan via `<proposed_plan>` for user approval before any file writes, deletions, or git mutations. When enabled, write/delete/mutate-git-log permissions are force-asked regardless of user settings.
129+
130+
**Key UI features**: `@` file mentions in the prompt input, `Ctrl+O` to view live process stdout, `Ctrl+V` to paste images, `Ctrl+X` to clear images, Shift+Enter for newlines, `Shift+Tab` to toggle Plan Mode, pluggable statusline, MCP server status display, undo selector, and permission prompts.
125131

126132
**CLI flags**: `-p <prompt>` / `--prompt` to auto-submit a prompt on launch, `-r [sessionId]` / `--resume [sessionId]` to resume a session or show the session picker, `-v` / `--version`, `-h` / `--help`.
127133

‎docs/plan-mode.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Plan Mode
2+
3+
Plan Mode（规划模式）是 Deep Code 内置的一种协作模式。在 Plan Mode 下，AI 助手会与你共同制定详细的实施方案，但**不会执行任何会修改代码的操作**。先规划、再实现，让复杂任务的每一步都有据可查。
4+
5+
## 为什么需要 Plan Mode
6+
7+
直接让 AI 改代码适合简单任务，但面对复杂的跨文件重构、新功能开发或架构调整时，常见的问题是：
8+
9+
- AI 在缺乏全貌的情况下就开始改代码，导致方向偏离
10+
- 缺少共识就动手，后续来回修正成本高
11+
- 修改与规划混在一起，难以追溯决策依据
12+
13+
Plan Mode 把"想清楚"和"动手做"拆成两个阶段，先在规划阶段充分探索、提问、达成共识，形成一份决策完备的方案再进入实现。
14+
15+
## 启用 Plan Mode
16+
17+
有两种方式可以进入 Plan Mode：
18+
19+
| 方式 | 操作 |
20+
| ---- | ---- |
21+
| 快捷键 | 在输入框中按 `Shift+Tab`，可随时在 Plan Mode 和 Default Mode 之间切换 |
22+
| 斜杠命令 | 输入 `/plan`，或输入 `/` 打开命令菜单后选择 `/plan` |
23+
24+
进入 Plan Mode 后，输入框右上角会显示黄色 `💡 Plan mode` 提示，表明当前处于规划模式。
25+
26+
退出 Plan Mode 同样使用 `Shift+Tab` 切换，或在输出方案后选择 "switch to Default mode"。
27+
28+
## Plan Mode 下的行为
29+
30+
### AI 的三个规划阶段
31+
32+
进入 Plan Mode 后，AI 助手会遵循一个三阶段的协作流程：
33+
34+
1. **环境摸底（Phase 1）**：先通过阅读文件、搜索代码、检查配置等方式理解项目现状，尽可能通过探索消除不确定性，而不是直接提问。
35+
2. **意图对齐（Phase 2）**：围绕你的目标和偏好提问，明确成功标准、范围边界、约束条件和关键取舍。
36+
3. **方案推敲（Phase 3）**：在意图稳定后，讨论具体实现路径，包括接口设计、数据流、边界情况、测试策略等，直到方案"决策完备"。
37+
38+
在每个阶段，AI 都会通过 `AskUserQuestion` 工具与你交互，提供具体的选项供你选择。
39+
40+
### 严格限制：禁止修改操作
41+
42+
Plan Mode 的核心规则是**只规划，不动手**。例如以下操作是**被允许**的：
43+
44+
- 读取和搜索文件、配置、类型定义、文档
45+
- 静态分析和代码探索
46+
- 运行不影响仓库追踪文件的干运行命令（如 `--dry-run`）
47+
- 运行测试、构建等可能写入缓存或构建产物（如 `target/`、`.cache/`）但不修改仓库追踪文件的命令
48+
49+
以下操作则**不被允许**：
50+
51+
- 编辑或写入文件
52+
- 运行会修改文件的格式化或 lint 工具
53+
- 应用补丁、迁移或代码生成
54+
- 其他目的为实现方案而非完善方案的副作用操作
55+
56+
### 权限强制限制
57+
58+
即使在 `settings.json` 中配置了对写入、删除等操作自动放行，Plan Mode 也会**强制将这些权限升级为"询问"**（ask）。具体来说，以下权限范围在 Plan Mode 下始终需要确认：
59+
60+
| 权限范围 | 说明 |
61+
| -------- | ---- |
62+
| `write-in-cwd` | 在工作区内创建或覆写文件 |
63+
| `write-out-cwd` | 在工作区外创建或覆写文件 |
64+
| `delete-in-cwd` | 删除工作区内的文件 |
65+
| `delete-out-cwd` | 删除工作区外的文件 |
66+
| `mutate-git-log` | 修改 Git 历史 |
67+
68+
这一设计确保即使权限配置较为宽松，Plan Mode 也不会意外修改你的代码。
69+
70+
## 输出方案
71+
72+
当 AI 认为方案已经决策完备，它就会在回复一个 `<proposed_plan>` 块：
73+
74+
```xml
75+
<proposed_plan>
76+
方案内容（使用 Markdown 格式）
77+
</proposed_plan>
78+
```
79+
80+
方案通常包含以下部分：
81+
82+
- **标题**：方案名称
83+
- **Summary**：简要概述
84+
- **Key Changes / Implementation Changes**：关键变更，以行为描述为主（而非文件清单）
85+
- **Test Plan**：测试用例和场景
86+
- **Assumptions**：做出的假设和选择的默认方案
87+
88+
方案输出后，你不需要输入任何额外内容，Deep Code 会自动弹出选择界面：
89+
90+
| 选项 | 作用 |
91+
| ---- | ---- |
92+
| **1. implement this plan** | 退出 Plan Mode，自动发送实现指令，让 AI 开始按方案写代码 |
93+
| **2. stay in Plan mode** | 保持在 Plan Mode，继续修改或完善方案 |
94+
| **3. switch to Default mode** | 退出 Plan Mode，回到默认模式（不自动开始实现） |
95+
96+
你可以用数字键 `1-3` 直接选择，也可以用 `↑/↓` 移动光标后按 `Enter` 确认。按 `Esc` 等同于选择 "stay in Plan mode"。
97+
98+
## Plan Mode 与 UpdatePlan 工具的区别
99+
100+
Plan Mode 是一种**对话协作模式**，最终产物是 `<proposed_plan>` 块中的完整方案。
101+
102+
`UpdatePlan` 是 Deep Code 的**任务进度清单工具**（对应 `UpdatePlan` 工具），用于在执行过程中展示步骤进度。它不会进入或退出 Plan Mode，也不是最终规划产物。
103+
104+
两者可以配合使用：在实现阶段，AI 可能会使用 `UpdatePlan` 来跟踪复杂任务的执行进度，但方案本身已在 Plan Mode 中确定。
105+
106+
## 典型使用场景
107+
108+
### 1. 新功能开发
109+
110+
```
111+
给用户列表加上分页和搜索功能。
112+
```
113+
114+
在 Plan Mode 下，AI 会先了解现有代码结构、路由、数据模型，然后与你讨论分页方式（游标还是偏移）、搜索范围、API 变更等问题，最后输出一份完整方案。
115+
116+
### 2. 代码重构
117+
118+
```
119+
把 UserService 中混杂的业务逻辑拆分到独立的 service 中。
120+
```
121+
122+
AI 会先分析 `UserService` 的依赖关系和调用方，给出拆分方案、迁移步骤和兼容性考虑。
123+
124+
### 3. 架构评审
125+
126+
```
127+
分析当前项目的认证流程，给出安全改进建议。
128+
```
129+
130+
AI 会遍历认证相关代码，识别潜在风险，并以方案形式给出具体的改进步骤。

‎docs/plan-mode_en.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Plan Mode
2+
3+
Plan Mode is a built-in collaboration mode in Deep Code. When Plan Mode is active, the AI assistant works with you to create a detailed implementation plan, but **does not perform any code-modifying actions**. Plan first, implement later—giving every step of a complex task a clear rationale.
4+
5+
## Why Plan Mode
6+
7+
Asking the AI to "just do it" works well for simple tasks, but with complex cross-file refactors, feature development, or architectural changes, common pitfalls include:
8+
9+
- The AI starts editing without a full picture, leading to wrong directions
10+
- No shared understanding before acting, causing expensive back-and-forth corrections
11+
- Implementation and planning mixed together, making it hard to trace decisions
12+
13+
Plan Mode separates "thinking" from "doing." First, explore, ask questions, and reach agreement during the planning phase. Then, once the plan is decision-complete, move on to implementation.
14+
15+
## Enabling Plan Mode
16+
17+
You can enter Plan Mode in two ways:
18+
19+
| Method | Action |
20+
| ------ | ------ |
21+
| Keyboard shortcut | Press `Shift+Tab` in the input box to toggle between Plan Mode and Default Mode |
22+
| Slash command | Type `/plan`, or type `/` to open the command menu and select `/plan` |
23+
24+
Once active, a yellow `💡 Plan mode` indicator appears in the top-right corner of the input area.
25+
26+
To leave Plan Mode, toggle again with `Shift+Tab`, or select "switch to Default mode" after reviewing a proposed plan.
27+
28+
## Behavior in Plan Mode
29+
30+
### Three Planning Phases
31+
32+
In Plan Mode, the AI follows a three-phase collaboration workflow:
33+
34+
1. **Ground in the environment (Phase 1)** — Understand the current project state by reading files, searching code, and checking configuration. Resolve unknowns through exploration before asking questions.
35+
2. **Intent chat (Phase 2)** — Ask about goals and preferences to clarify success criteria, scope boundaries, constraints, and key tradeoffs.
36+
3. **Implementation chat (Phase 3)** — Once intent is stable, discuss the concrete implementation approach: API design, data flow, edge cases, testing strategy, and so on, until the spec is "decision complete."
37+
38+
In each phase, the AI interacts with you through the `AskUserQuestion` tool, offering concrete options to choose from.
39+
40+
### Strict Rules: No Mutations
41+
42+
Plan Mode's core rule: **plan only, don't touch code**. The following actions are **allowed**:
43+
44+
- Reading and searching files, configs, type definitions, and docs
45+
- Static analysis and code exploration
46+
- Running dry-run commands that don't modify repo-tracked files
47+
- Running tests or builds that may write to caches or build artifacts (e.g. `target/`, `.cache/`) without altering tracked files
48+
49+
The following actions are **not allowed**:
50+
51+
- Editing or writing files
52+
- Running formatters or linters that rewrite files
53+
- Applying patches, migrations, or code generation
54+
- Side-effectful commands whose purpose is to execute the plan rather than refine it
55+
56+
### Permission Restrictions
57+
58+
Even if your `settings.json` is configured to auto-allow write, delete, or similar operations, Plan Mode **forcibly escalates these to "ask."** Specifically, the following permission scopes always require confirmation in Plan Mode:
59+
60+
| Permission scope | Description |
61+
| ---------------- | ----------- |
62+
| `write-in-cwd` | Create or overwrite files within the workspace |
63+
| `write-out-cwd` | Create or overwrite files outside the workspace |
64+
| `delete-in-cwd` | Delete files within the workspace |
65+
| `delete-out-cwd` | Delete files outside the workspace |
66+
| `mutate-git-log` | Modify Git history |
67+
68+
This ensures that Plan Mode won't accidentally modify your code, even with permissive settings.
69+
70+
## The Proposed Plan
71+
72+
When the AI considers the plan decision-complete—meaning an implementer needs to make no further decisions—it outputs a `<proposed_plan>` block in the response:
73+
74+
```xml
75+
<proposed_plan>
76+
Plan content (in Markdown)
77+
</proposed_plan>
78+
```
79+
80+
A plan typically includes:
81+
82+
- **Title**: The plan name
83+
- **Summary**: A brief overview
84+
- **Key Changes / Implementation Changes**: Critical changes described at the behavior level (not a file-by-file inventory)
85+
- **Test Plan**: Test cases and scenarios
86+
- **Assumptions**: Assumptions made and defaults chosen
87+
88+
After the plan is output, Deep Code automatically shows a choice dialog—no extra input needed:
89+
90+
| Option | Effect |
91+
| ------ | ------ |
92+
| **1. implement this plan** | Leave Plan Mode and automatically send an implementation prompt so the AI starts coding |
93+
| **2. stay in Plan mode** | Stay in Plan Mode to continue refining the plan |
94+
| **3. switch to Default mode** | Leave Plan Mode and return to Default mode without starting implementation |
95+
96+
You can press `1-3` to select directly, or use `↑/↓` to move the cursor and `Enter` to confirm. Pressing `Esc` is equivalent to choosing "stay in Plan mode."
97+
98+
## Plan Mode vs. UpdatePlan Tool
99+
100+
Plan Mode is a **collaborative conversation mode** whose final artifact is the complete plan inside a `<proposed_plan>` block.
101+
102+
`UpdatePlan` is Deep Code's **progress checklist tool** that shows step-by-step progress during execution. It does not enter or exit Plan Mode and is not the final planning artifact.
103+
104+
The two can work together: during implementation, the AI may use `UpdatePlan` to track progress on complex tasks, but the plan itself is already settled in Plan Mode.
105+
106+
## Common Use Cases
107+
108+
### 1. New Feature Development
109+
110+
```
111+
Add pagination and search to the user list.
112+
```
113+
114+
In Plan Mode, the AI first understands the existing code structure, routes, and data models, then discusses pagination style (cursor vs. offset), search scope, API changes, etc., before producing a complete plan.
115+
116+
### 2. Code Refactoring
117+
118+
```
119+
Split the tangled business logic in UserService into separate services.
120+
```
121+
122+
The AI analyzes `UserService` dependencies and call sites, then proposes a split plan with migration steps and compatibility considerations.
123+
124+
### 3. Architecture Review
125+
126+
```
127+
Analyze the current authentication flow and suggest security improvements.
128+
```
129+
130+
The AI walks through auth-related code, identifies potential risks, and delivers concrete improvement steps as a plan.

0 commit comments

Comments
 (0)