merge: expand README feature guide

Author: liwangping

README.md

@@ -52,20 +52,21 @@ do-code
 ## What it does
 
 - **Works in real repositories** — read and attach files, edit code, run shell commands, inspect Git diffs, and run tests.
-- **Uses your model provider** — built-in setup for Ark, Bailian, DeepSeek, MiniMax, Z.AI, and ModelScope, plus OpenAI-compatible, Anthropic, and Gemini services.
-- **Keeps execution controlled** — planning and permission modes are independent, and every edit gets a local checkpoint for inspection or recovery.
+- **Uses your model provider** — built-in setup for Volcengine Ark, Alibaba ModelStudio, DeepSeek, MiniMax, Z.AI, and ModelScope; Custom Provider supports OpenAI-compatible, Anthropic, and Gemini APIs.
+- **Keeps execution controlled** — planning and permission modes are independent, and built-in file edits and patches receive local checkpoints for inspection or recovery.
 
 Type `/` to browse commands and `@` to attach workspace files:
 
 ```text
-/plan                 Explore and propose a plan in read-only mode
-/permissions          Choose Ask / Auto / Full Access
-/model                 View or switch model presets
-/resume                Restore a previous session
+/plan · /permissions · /model · /resume
+/status · /stats · /compact · /diff
+/memory · /rewind · /export · /language
 @src/app.ts           Add a file to the current context
 !npm test             Run a command under the current permission mode
 ```
 
+Use `/thinking` and `/effort` to tune reasoning during a session; add `--persist` to save the choice as the default for future sessions. The interface supports English, Simplified Chinese, Japanese, Korean, Spanish, and French through `--language` or `/language`.
+
 ## Run it your way
 
 ### Interactive terminal
@@ -76,31 +77,71 @@ do-code --continue
 do-code resume <session-id>
 ```
 
+### Sessions and context
+
+Continue the latest project session with `do-code --continue`, or choose one with `resume` and `/resume`:
+
+```bash
+do-code sessions list
+do-code sessions search "authentication"
+do-code sessions rename <session-id> "Auth cleanup"
+do-code sessions delete <session-id>
+do-code sessions export <session-id> md ./session.md
+```
+
+Use `/stats` to inspect context use and `/compact` to compact it on demand. Near the context limit, do-code compacts automatically while retaining important paths, commands, decisions, and verification state.
+
+### Project instructions and isolation
+
+Layered `AGENTS.md` instructions follow the workspace hierarchy; inspect or reload them with `/memory`. Start an isolated Git worktree with `do-code --worktree` or `do-code --worktree=<name>`, and inspect do-code worktrees with `do-code worktrees`.
+
+### Profiles and extensions
+
+Agent profiles can select a model, approval mode, instructions, step limit, and tool allow/deny lists. Inspect them with `do-code agents` and select one with `do-code --agent <name>`. Browse Markdown commands and skills with `/extensions`; use `do-code extensions` for a summary of commands, skills, and configured MCP servers.
+
 ### Scripts and CI
 
-`run` produces stable JSON or JSONL output for automation:
+`run` produces stable JSON or JSONL output for automation. Tasks can come from an argument or `--task-file`; `--max-steps` and `--timeout` set execution budgets. `--artifact-dir` stores the frozen configuration, event stream, result, and patch artifacts.
 
 ```bash
-do-code run --yes --output-format stream-json "Fix the failing test and verify it"
+do-code run --yes --output-format stream-json \
+  --task-file task.txt --artifact-dir ./artifacts \
+  --max-steps 40 --timeout 600
 ```
 
-Use `do-code acp` for the ACP standard input/output protocol. See the [Headless / JSONL protocol](docs/headless-protocol.md).
+Use `do-code acp` for the ACP standard input/output protocol. See the [Headless / JSONL protocol](docs/headless-protocol.md) for the supported automation contract.
 
 ### Image input
 
-Attach up to four PNG, JPEG, GIF, or WebP images with repeated `--image` in headless mode:
+Attach up to four PNG, JPEG, GIF, or WebP images with repeated `--image` in headless mode. The selected model must support image input.
 
 ```bash
 do-code run --image screenshots/bug.png --image screenshots/diagram.webp "Describe these images"
 ```
 
 In the interactive TUI, type `@path/to/image.png` or use `/paste-image` to import an image from the system clipboard. Use `/remove-image <index|name>` to remove a pending attachment. Each image is limited to 10 MB and the prompt total is limited to 20 MB. Imported files are copied to `~/.local/share/do-code/projects/<project-key>/sessions/<session-id>/attachments/`; persisted messages contain only relative references such as `attachments/image_xxx.png`, never Base64 data or the original absolute path. Set `DO_CODE_DATA_DIR` to override the global data root. Existing project-local `.do-code` data is migrated to the user-managed project directory when the project is next accessed.
 
+### Useful CLI commands
+
+```bash
+do-code config show          # Inspect effective model configuration
+do-code doctor               # Check model, workspace, and local tools
+do-code sessions list        # List project sessions
+do-code extensions           # Inspect commands, skills, and MCP configuration
+do-code agents               # List agent profiles
+do-code worktrees            # List isolated worktrees
+do-code errors list          # List recent error reports
+```
+
 ## Safety and data
 
 The default **Ask** mode requests confirmation for high-risk actions. **Auto** handles ordinary workspace changes automatically. **Full Access** is intended only for trusted workspaces or CI.
 
-Sessions, checkpoints, error reports, and credentials stay on your machine by default. To inspect a failure:
+Configuration is stored under `~/.config/do-code/`; project sessions, attachments, checkpoints, and error reports are stored under `~/.local/share/do-code/projects/<project-key>/`. `DO_CODE_DATA_DIR` overrides the data root. Credentials and project data stay on your machine by default.
+
+Sandbox settings can use local execution, macOS Seatbelt, or a container, depending on configuration and host support. Permission mode and sandbox configuration are separate controls.
+
+To inspect a failure:
 
 ```bash
 do-code errors list
@@ -113,16 +154,16 @@ do-code errors show <error-id>
 - [Bad case feedback and diagnostics](docs/bad-case-feedback.md)
 - [Headless / JSONL protocol](docs/headless-protocol.md)
 - [Architecture](docs/architecture.md)
+- [Local development](docs/local-development.md)
 - [Personal release process](docs/releasing.md)
 
 ## Contributing
 
 Issues and pull requests are welcome. Please read the [contributing guide](CONTRIBUTING.md) and [security policy](SECURITY.md) before submitting a change.
 
 ```bash
-npm test
-npm run typecheck
-npm run build
+npm run verify:local
+npm run build:agent
 ```
 
 ## License

README.zh-CN.md

@@ -52,20 +52,21 @@ do-code
 ## 用 do-code 做什么
 
 - **在真实工作区完成任务**：读取和引用文件、修改代码、执行 Shell 命令、查看 Git Diff、运行测试。
-- **接入自己的模型**：内置火山方舟、百炼、DeepSeek、MiniMax、智谱、ModelScope，也支持 OpenAI-compatible、Anthropic 与 Gemini 服务。
-- **保持执行可控**：计划模式与权限模式彼此独立；每次编辑会创建本地检查点，方便检查或恢复。
+- **接入自己的模型服务**：内置 Volcengine Ark、Alibaba ModelStudio、DeepSeek、MiniMax、Z.AI 和 ModelScope；Custom Provider 支持 OpenAI-compatible、Anthropic 与 Gemini API。
+- **保持执行可控**：计划模式与权限模式彼此独立；内置文件编辑和补丁会创建本地检查点，方便检查或恢复。
 
 输入 `/` 浏览命令，输入 `@` 引用工作区文件：
 
 ```text
-/plan                 在只读模式下探索并提出计划
-/permissions          选择 Ask / Auto / Full Access
-/model                 查看或切换模型预设
-/resume                恢复历史会话
+/plan · /permissions · /model · /resume
+/status · /stats · /compact · /diff
+/memory · /rewind · /export · /language
 @src/app.ts           将文件加入当前上下文
 !npm test             运行命令（遵循当前权限）
 ```
 
+使用 `/thinking` 和 `/effort` 可在会话中调整推理设置；添加 `--persist` 可保存为未来会话的默认值。界面支持 English、Simplified Chinese、Japanese、Korean、Spanish 和 French，可通过 `--language` 或 `/language` 切换。
+
 ## 运行方式
 
 ### 交互式终端
@@ -76,21 +77,71 @@ do-code --continue
 do-code resume <session-id>
 ```
 
+### 会话与上下文
+
+使用 `do-code --continue` 继续当前项目的最新会话，也可通过 `resume` 和 `/resume` 选择会话：
+
+```bash
+do-code sessions list
+do-code sessions search "authentication"
+do-code sessions rename <session-id> "Auth cleanup"
+do-code sessions delete <session-id>
+do-code sessions export <session-id> md ./session.md
+```
+
+使用 `/stats` 查看上下文用量，使用 `/compact` 手动压缩。接近上下文上限时，do-code 会自动压缩，并保留重要路径、命令、决策和验证状态。
+
+### 项目指令与隔离
+
+分层 `AGENTS.md` 指令遵循工作区层级，可通过 `/memory` 查看或重新加载。使用 `do-code --worktree` 或 `do-code --worktree=<name>` 在隔离 Git worktree 中运行，使用 `do-code worktrees` 查看 do-code worktree。
+
+### 配置档与扩展
+
+Agent profile 可选择 model、approval mode、instructions、step limit 和 tool allow/deny lists。使用 `do-code agents` 查看，通过 `do-code --agent <name>` 选择。使用 `/extensions` 浏览 Markdown commands 和 skills；使用 `do-code extensions` 汇总查看 commands、skills 与已配置的 MCP servers。
+
 ### 脚本与 CI
 
-`run` 提供稳定的 JSON / JSONL 输出，适合外部自动化调用：
+`run` 提供稳定的 JSON / JSONL 输出，适合外部自动化调用。任务可来自命令参数或 `--task-file`；`--max-steps` 与 `--timeout` 控制执行预算。`--artifact-dir` 保存冻结配置、事件流、结果和补丁产物。
+
+```bash
+do-code run --yes --output-format stream-json \
+  --task-file task.txt --artifact-dir ./artifacts \
+  --max-steps 40 --timeout 600
+```
+
+也可通过 `do-code acp` 使用 ACP 标准输入/输出协议。其自动化契约详见 [Headless / JSONL 协议](docs/headless-protocol.md)。
+
+### 图片输入
+
+在 headless 模式中重复使用 `--image`，最多可附加四张 PNG、JPEG、GIF 或 WebP 图片。所选模型必须支持图片输入。
 
 ```bash
-do-code run --yes --output-format stream-json "修复失败测试并验证"
+do-code run --image screenshots/bug.png --image screenshots/diagram.webp "描述这些图片"
 ```
 
-也可通过 `do-code acp` 使用 ACP 标准输入/输出协议。详见 [Headless / JSONL 协议](docs/headless-protocol.md)。
+在交互式 TUI 中，输入 `@path/to/image.png`，或使用 `/paste-image` 从系统剪贴板导入图片。使用 `/remove-image <index|name>` 可移除待发送附件。每张图片最大 10 MB，单次提示中的图片总量最大 20 MB。导入的文件会复制到 `~/.local/share/do-code/projects/<project-key>/sessions/<session-id>/attachments/`；持久化消息只保存 `attachments/image_xxx.png` 这类相对引用，不保存 Base64 数据或原始绝对路径。设置 `DO_CODE_DATA_DIR` 可覆盖全局数据根目录。项目内已有的 `.do-code` 数据会在下次访问该项目时迁移到用户管理的项目目录。
+
+### 常用 CLI 命令
+
+```bash
+do-code config show          # 查看生效的模型配置
+do-code doctor               # 检查模型、工作区与本地工具
+do-code sessions list        # 列出项目会话
+do-code extensions           # 检查 commands、skills 与 MCP 配置
+do-code agents               # 列出 agent profiles
+do-code worktrees            # 列出隔离 worktrees
+do-code errors list          # 列出近期错误报告
+```
 
 ## 安全与数据
 
 默认的 **Ask** 模式会在高风险操作前请求确认；**Auto** 自动处理普通工作区改动；**Full Access** 仅适用于已信任的工作区或 CI。
 
-会话、检查点、错误报告与凭据默认都留在本机。出现异常时：
+配置保存在 `~/.config/do-code/`；项目会话、附件、检查点和错误报告保存在 `~/.local/share/do-code/projects/<project-key>/`。`DO_CODE_DATA_DIR` 可覆盖数据根目录。凭据与项目数据默认都留在本机。
+
+Sandbox 设置可使用 local execution、macOS Seatbelt 或 container，具体取决于配置和宿主支持。权限模式与 sandbox 配置是彼此独立的控制项。
+
+出现异常时：
 
 ```bash
 do-code errors list
@@ -103,16 +154,16 @@ do-code errors show <error-id>
 - [Bad Case 回流与错误诊断](docs/bad-case-feedback.md)
 - [Headless / JSONL 协议](docs/headless-protocol.md)
 - [架构说明](docs/architecture.md)
+- [本地开发流程](docs/local-development.md)
 - [个人发布流程](docs/releasing.md)
 
 ## 参与贡献
 
 欢迎提交 Issue 与 Pull Request。开始前请阅读 [贡献指南](CONTRIBUTING.md) 和 [安全策略](SECURITY.md)。
 
 ```bash
-npm test
-npm run typecheck
-npm run build
+npm run verify:local
+npm run build:agent
 ```
 
 ## License