anti-trace 0.1.0 → 0.1.1

package/README.en.md

@@ -1,154 +1,155 @@
-# Anti-trace
-
-[中文](README.md) | **English**
-
-Anti-trace is an AI coding agent that runs in your terminal. It can read and edit code, execute shell commands, find project files, and decide what to do next based on the results. Bring your own API credentials to connect a model provider through OpenAI Chat Completions, OpenAI Responses, or Anthropic Messages.
-
-![Anti-trace proposed architecture: the existing agent foundation, planned feature changes, validation, and hot restart](docs/assets/target-architecture.svg)
-
-## What it can do
-
-- **Understand a project:** read source files, trace module relationships, and explain code.
-- **Write and change code:** implement features, fix bugs, refactor code, or write documentation from your instructions.
-- **Run development tasks:** use the shell to find files, run builds and tests, and investigate problems using command output.
-- **Continue previous work:** save project conversations and restore them with `/resume`; track context usage and compact conversation history.
-- **Work with text and images:** multiline editing, long-text pasting, image input, and draft undo/redo.
-
-## Quick start
-
-You need Node.js 22 or newer and API credentials for your chosen model provider.
-
-```sh
-git clone https://github.com/sadgsk/Anti-trace.git
-cd Anti-trace
-npm install
-```
-
-Copy [byok.example.json](byok.example.json) to `~/.anti-trace/profiles/local/configs/main.json` in your home directory (create the directories first) and configure:
-
-- The connection's API key and service URL.
-- The model ID, context window, and output limit.
-- `currentModel`: the model configuration key to use.
-
-The default `main` entry contains a placeholder URL and model ID. Replace them before making a model request. Then start the CLI:
-
-```sh
-npm start
-```
-
-To register the equivalent local commands `ati` and `anti-trace`, run these commands from this repository:
-
-```sh
-npm run build
-npm link
-```
-
-You can then run `ati` or `anti-trace` from any working directory; that directory becomes the CLI's cwd, while model configuration is loaded from your user data directory. `CLI_AGENT_CONFIG` can explicitly select another JSON file. The commands run the compiled `dist` files, so run `npm run build` again after source changes; linking again is unnecessary. `npm link` registers the commands locally and does not publish to npm.
-
-macOS and Linux use Bash. Windows prefers PowerShell 7, falling back to Windows PowerShell 5.1. Installing Git for Windows also enables the Bash tool for Bash scripts and POSIX commands. For a custom Git installation, set `ANTI_TRACE_GIT_BASH_PATH` to the absolute path of its `bin\bash.exe` before startup. You can launch Anti-trace from CMD or PowerShell; each tool selects its own interpreter. Commands default to a 120-second timeout.
-
-Describe a task directly in the conversation, for example:
-
-```text
-Explain this project's entry points and main modules.
-Fix this function's handling of empty input and add a test.
-Run the build, investigate the errors, and update the relevant code.
-```
-
-The agent reads files, edits code, and runs commands as needed. These actions affect your project files directly; use a recoverable copy for initial evaluation.
-
-## Model providers
-
-Use BYOK JSON to configure your own model service:
-
-| API | Configuration value |
-|---|---|
-| OpenAI Chat Completions | `openai-completions` |
-| OpenAI Responses | `openai-responses` |
-| Anthropic Messages | `anthropic-messages` |
-
-Models reference a connection through `connection`; `currentModel` selects a key in `models`. Set `apiKey` directly or use `apiKeyEnv` to reference a process environment variable.
-
-The user data root defaults to `~/.anti-trace`; override it with `ANTI_TRACE_HOME`. Model configurations and `/config` creations use `profiles/local/configs/`. The `local` profile is the current local user; the code accepts a `profileId` for future user separation without implementing login.
-
-Startup selects an explicit `CLI_AGENT_CONFIG`, the project's last selection, the user's default selection, or the sole valid configuration, in that order. Multiple configurations without a saved selection require `/config`. Explicit configuration/model choices update the user default; reopening a project does not overwrite that default with its project selection. Missing saved paths warn and fall back; invalid explicit paths fail. Workspace `byok.json`, `.env` and old storage directories are not automatically read.
-
-```text
-~/.anti-trace/
-├── preferences.json                     # Machine-wide language preference
-└── profiles/local/
-    ├── configs/                         # Model connection configuration
-    ├── default-model.json               # Default selection for new projects
-    └── projects/<SHA-256 of workspace>/
-        ├── project.json                 # Workspace path
-        ├── last-model.json              # Project model/config selection
-        ├── sessions/                    # Conversations and image attachments
-        └── tool-results/                # Complete tool output
-```
-
-Selection files contain only configuration paths and model keys. Conversations and tool output are separated by workspace and profile, while language is shared on this machine. File operations and shells keep the startup cwd. Image conversion uses the system temporary directory. Old conversations are not migrated; existing files remain untouched.
-
-Anthropic Messages defaults to `32000` when `maxOutputTokens` is omitted, capped at the configured `contextWindow` if it is smaller. An explicit output limit takes precedence.
-
-Include any required version prefix in `baseUrl`, such as `/v1`. Alternatively, select connection presets and models from the [provider configuration example](byok.providers.example.json), then set the corresponding API key environment variables. The example includes 36 connection options across nine providers, with explicit rules for supported protocols, regions, and models.
-
-## Common commands
-
-Type `/` to open the command menu; use arrows to select, Enter to confirm, Tab to complete and Esc to return. Model, effort, thinking, thinking display, session resume and configuration commands open selection screens without typed arguments. Explicit arguments remain compatible. Input starts at the bottom; use the mouse wheel or PgUp/PgDn to review history, Ctrl+End to return to the latest output, and Shift+drag to select text.
-
-| Command | Purpose |
-|---|---|
-| `/help` | Show help |
-| `/new` | Start a new session |
-| `/resume` | Select and restore a session with arrow keys |
-| `/model` | Select from models in the current configuration |
-| `/config` | Choose, add or edit configurations; add models to one file and edit each field on a separate page |
-| `/reload` | Reload model configuration |
-| `/thinking` | Select reasoning on/off |
-| `/effort` | Select low/medium/high/xhigh/max with arrow keys |
-| `/thinking-display` | Select the default reasoning text visibility |
-| `/language` | Switch between Chinese and English and remember the preference |
-| `/context [positive integer]` | View or adjust the context window |
-| `/compact` | Attempt manual context compaction |
-| `/exit` | Exit |
-
-The complete TUI is ready for trial; see the [architecture and interaction notes](docs/architecture.md#4-分层) and [progress record](docs/progress.md) for validation and remaining work. It includes Markdown, code and tables, tool cards and diffs, permission approval, file completion with `@`, and attachment indicators. Ctrl+O expands/collapses content at the current reading position, or opens the latest tool when following live output; Shift+Tab cycles permission modes. Use `npm start -- --auto-edit` or `npm start -- --yolo` to choose a startup mode explicitly.
-
-Enter submits. Shift/Alt+Enter, or a backslash followed by Enter, inserts a newline. Ctrl+C interrupts generation or clears the draft; when idle with an empty draft, it exits. Ctrl+Z undoes; Ctrl+Y redoes. Shortcut recognition depends on the terminal.
-
-`/reload` reloads model configuration while preserving the current model selection and reasoning preferences. `/new` inherits the current settings; `/resume` resolves saved model references against the loaded catalog. The reasoning display switch only affects display, not model requests.
-
-## Project direction
-
-The project is in early development. Its long-term goal is to let users describe a feature in natural language, have the agent modify its own tools or CLI interface, and apply those changes through a hot restart.
-
-This capability has not been implemented. The diagram above shows the proposed design. Current work focuses on the underlying model integration, tool execution, sessions, and context management.
-
-- [ ] Dynamically modify tools, the CLI interface, and other capabilities from natural-language requests.
-- [ ] Validate capability changes and load them through a hot restart.
-- [x] Provider presets, reasoning controls, and the unified settings workflow.
-- [ ] Improve TUI interaction in v1.3.
-- [x] Establish reproducible offline tests and Windows/Linux/macOS CI.
-- [ ] Expand real-model and native-terminal acceptance checks.
-- [ ] Fix remaining issues with tool pairing and context-overflow error display.
-
-## Known limitations
-
-- Windows requires a working PowerShell or Git Bash installation. Without Git Bash, only PowerShell is exposed. An invalid explicit Bash path produces a configuration error. See [future-issues.md](docs/future-issues.md).
-- Premature display of recoverable context-overflow errors still needs work. Interrupted tool-batch pairing was fixed in the TUI implementation; see the [review records](docs/review-records.md).
-- Local HTTP SSE and macOS POSIX PTY verification records exist. Coverage of real models, clipboards, and other terminal platforms remains incomplete.
-- Formal tests live in `tests/`. Run `npm test` for offline tests or `npm run check` for type checks, tests and a build. See the [testing guide](docs/testing.md) for commands, coverage and the three-platform CI matrix. Real-model checks have a separate explicit entry point.
-
-## Development documentation and origins
-
-The detailed development documents are currently in Chinese.
-
-- [Development progress](docs/progress.md): current status, pending work, and development history.
-- [Architecture](docs/architecture.md): module responsibilities and design.
-- [Testing and CI](docs/testing.md): commands, test authoring, isolation, coverage and the CI matrix (Chinese).
-
-The project started by studying and referencing [Pi](https://github.com/earendil-works/pi). Some foundational code was adapted from Pi. Anti-trace uses its own `Harness` and feature design, and does not currently depend on Pi runtime packages.
-
-## License
-
-[MIT](LICENSE). Portions derived from Pi retain their original copyright and license notice.
+# Anti-trace
+
+[中文](README.md) | **English**
+
+Anti-trace is an AI coding agent that runs in your terminal. It can read and edit code, execute shell commands, find project files, and decide what to do next based on the results. Bring your own API credentials to connect a model provider through OpenAI Chat Completions, OpenAI Responses, or Anthropic Messages.
+
+![Anti-trace proposed architecture: the existing agent foundation, planned feature changes, validation, and hot restart](docs/assets/target-architecture.svg)
+
+## What it can do
+
+- **Understand a project:** read source files, trace module relationships, and explain code.
+- **Write and change code:** implement features, fix bugs, refactor code, or write documentation from your instructions.
+- **Run development tasks:** use the shell to find files, run builds and tests, and investigate problems using command output.
+- **Continue previous work:** save project conversations and restore them with `/resume`; track context usage and compact conversation history.
+- **Work with text and images:** multiline editing, long-text pasting, image input, and draft undo/redo.
+
+## Quick start
+
+You need Node.js 22 or newer and API credentials for your chosen model provider.
+
+```sh
+git clone https://github.com/sadgsk/Anti-trace.git
+cd Anti-trace
+npm install
+```
+
+Copy [byok.example.json](byok.example.json) to `~/.anti-trace/profiles/local/configs/main.json` in your home directory (create the directories first) and configure:
+
+- The connection's API key and service URL.
+- The model ID, context window, and output limit.
+- `currentModel`: the model configuration key to use.
+
+The default `main` entry contains a placeholder URL and model ID. Replace them before making a model request. Then start the CLI:
+
+```sh
+npm start
+```
+
+To register the equivalent local commands `ati` and `anti-trace`, run these commands from this repository:
+
+```sh
+npm run build
+npm link
+```
+
+You can then run `ati` or `anti-trace` from any working directory; that directory becomes the CLI's cwd, while model configuration is loaded from your user data directory. `CLI_AGENT_CONFIG` can explicitly select another JSON file. The commands run the compiled `dist` files, so run `npm run build` again after source changes; linking again is unnecessary. `npm link` registers the commands locally and does not publish to npm.
+
+macOS and Linux use Bash. Windows prefers PowerShell 7, falling back to Windows PowerShell 5.1. Installing Git for Windows also enables the Bash tool for Bash scripts and POSIX commands. For a custom Git installation, set `ANTI_TRACE_GIT_BASH_PATH` to the absolute path of its `bin\bash.exe` before startup. You can launch Anti-trace from CMD or PowerShell; each tool selects its own interpreter. Commands default to a 120-second timeout.
+
+Describe a task directly in the conversation, for example:
+
+```text
+Explain this project's entry points and main modules.
+Fix this function's handling of empty input and add a test.
+Run the build, investigate the errors, and update the relevant code.
+```
+
+The agent reads files, edits code, and runs commands as needed. These actions affect your project files directly; use a recoverable copy for initial evaluation.
+
+## Model providers
+
+Use BYOK JSON to configure your own model service:
+
+| API | Configuration value |
+|---|---|
+| OpenAI Chat Completions | `openai-completions` |
+| OpenAI Responses | `openai-responses` |
+| Anthropic Messages | `anthropic-messages` |
+
+Models reference a connection through `connection`; `currentModel` selects a key in `models`. Set `apiKey` directly or use `apiKeyEnv` to reference a process environment variable.
+
+The user data root defaults to `~/.anti-trace`; override it with `ANTI_TRACE_HOME`. Model configurations and `/config` creations use `profiles/local/configs/`. The `local` profile is the current local user; the code accepts a `profileId` for future user separation without implementing login.
+
+Startup selects an explicit `CLI_AGENT_CONFIG`, the project's last selection, the user's default selection, or the sole valid configuration, in that order. Multiple configurations without a saved selection require `/config`. Explicit configuration/model choices update the user default; reopening a project does not overwrite that default with its project selection. Missing saved paths warn and fall back; invalid explicit paths fail. Workspace `byok.json`, `.env` and old storage directories are not automatically read.
+
+```text
+~/.anti-trace/
+├── preferences.json                     # Machine-wide language preference
+└── profiles/local/
+    ├── configs/                         # Model connection configuration
+    ├── default-model.json               # Default selection for new projects
+    └── projects/<SHA-256 of workspace>/
+        ├── project.json                 # Workspace path
+        ├── last-model.json              # Project model/config selection
+        ├── sessions/                    # Conversations and image attachments
+        └── tool-results/                # Complete tool output
+```
+
+Selection files contain only configuration paths and model keys. Conversations and tool output are separated by workspace and profile, while language is shared on this machine. File operations and shells keep the startup cwd. Image conversion uses the system temporary directory. Old conversations are not migrated; existing files remain untouched.
+
+Anthropic Messages defaults to `32000` when `maxOutputTokens` is omitted, capped at the configured `contextWindow` if it is smaller. An explicit output limit takes precedence.
+
+Include any required version prefix in `baseUrl`, such as `/v1`. Alternatively, select connection presets and models from the [provider configuration example](byok.providers.example.json), then set the corresponding API key environment variables. The example includes 36 connection options across nine providers, with explicit rules for supported protocols, regions, and models.
+
+## Common commands
+
+Type `/` to open the command menu; use arrows to select, Enter to confirm, Tab to complete and Esc to return. Model, effort, thinking, thinking display, session resume and configuration commands open selection screens without typed arguments. Explicit arguments remain compatible. Input starts at the bottom; use the mouse wheel or PgUp/PgDn to review history, Ctrl+End to return to the latest output, and Shift+drag to select text.
+
+| Command | Purpose |
+|---|---|
+| `/help` | Show help |
+| `/new` | Start a new session |
+| `/resume` | Select and restore a session with arrow keys |
+| `/model` | Select from models in the current configuration |
+| `/config` | Choose, add or edit configurations; add models to one file and edit each field on a separate page |
+| `/reload` | Reload model configuration |
+| `/thinking` | Select reasoning on/off |
+| `/effort` | Select low/medium/high/xhigh/max with arrow keys |
+| `/thinking-display` | Select the default reasoning text visibility |
+| `/language` | Switch between Chinese and English and remember the preference |
+| `/context [positive integer]` | View or adjust the context window |
+| `/compact` | Attempt manual context compaction |
+| `/exit` | Exit |
+
+The complete TUI is ready for trial; see the [architecture and interaction notes](docs/architecture.md#4-分层) and [progress record](docs/progress.md) for validation and remaining work. It includes Markdown, code and tables, tool cards and diffs, permission approval, file completion with `@`, and attachment indicators. Ctrl+O expands/collapses content at the current reading position, or opens the latest tool when following live output; Shift+Tab cycles permission modes. Use `npm start -- --auto-edit` or `npm start -- --yolo` to choose a startup mode explicitly.
+
+Enter submits. Shift/Alt+Enter, or a backslash followed by Enter, inserts a newline. Ctrl+C interrupts generation or clears the draft; when idle with an empty draft, it exits. Ctrl+Z undoes; Ctrl+Y redoes. Shortcut recognition depends on the terminal.
+
+`/reload` reloads model configuration while preserving the current model selection and reasoning preferences. `/new` inherits the current settings; `/resume` resolves saved model references against the loaded catalog. The reasoning display switch only affects display, not model requests.
+
+## Project direction
+
+The project is in early development. Its long-term goal is to let users describe a feature in natural language, have the agent modify its own tools or CLI interface, and apply those changes through a hot restart.
+
+This capability has not been implemented. The diagram above shows the proposed design. Current work focuses on the underlying model integration, tool execution, sessions, and context management.
+
+- [ ] Dynamically modify tools, the CLI interface, and other capabilities from natural-language requests.
+- [ ] Validate capability changes and load them through a hot restart.
+- [x] Provider presets, reasoning controls, and the unified settings workflow.
+- [ ] Improve TUI interaction in v1.3.
+- [x] Establish reproducible offline tests and Windows/Linux/macOS CI.
+- [ ] Expand real-model and native-terminal acceptance checks.
+- [ ] Fix remaining issues with tool pairing and context-overflow error display.
+
+## Known limitations
+
+- Windows requires a working PowerShell or Git Bash installation. Without Git Bash, only PowerShell is exposed. An invalid explicit Bash path produces a configuration error. See [future-issues.md](docs/future-issues.md).
+- Premature display of recoverable context-overflow errors still needs work. Interrupted tool-batch pairing was fixed in the TUI implementation; see the [review records](docs/review-records.md).
+- Local HTTP SSE and macOS POSIX PTY verification records exist. Coverage of real models, clipboards, and other terminal platforms remains incomplete.
+- Formal tests live in `tests/`. Run `npm test` for offline tests or `npm run check` for type checks, tests and a build. See the [testing guide](docs/testing.md) for commands, coverage and the three-platform CI matrix. Real-model checks have a separate explicit entry point.
+
+## Development documentation and origins
+
+The detailed development documents are currently in Chinese.
+
+- [Development progress](docs/progress.md): current status, pending work, and development history.
+- [Architecture](docs/architecture.md): module responsibilities and design.
+- [Testing and CI](docs/testing.md): commands, test authoring, isolation, coverage and the CI matrix (Chinese).
+- [npm releases](docs/releases.md): connect npm to GitHub and publish stable releases using version tags (Chinese).
+
+The project started by studying and referencing [Pi](https://github.com/earendil-works/pi). Some foundational code was adapted from Pi. Anti-trace uses its own `Harness` and feature design, and does not currently depend on Pi runtime packages.
+
+## License
+
+[MIT](LICENSE). Portions derived from Pi retain their original copyright and license notice.

package/README.md

@@ -1,153 +1,154 @@
-# Anti-trace
-
-**中文** | [English](README.en.md)
-
-Anti-trace 是一个运行在终端里的 AI 编程 agent，可以帮你阅读和修改代码、执行 shell 命令、查找项目文件，并根据执行结果自主决定下一步动作。你可以使用自己的 API 密钥接入模型服务，目前支持 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages 三种接口。
-
-![Anti-trace 预计架构：现有 agent 基础与计划中的功能修改、验证和热启动流程（英文）](docs/assets/target-architecture.svg)
-
-## 能做什么
-
-- **理解项目**：阅读源码，梳理模块关系，解释代码逻辑。
-- **编写和修改代码**：根据需求实现功能、修复 bug、重构代码或编写文档。
-- **执行开发任务**：调用 shell 查找文件、运行构建和测试，并结合命令输出继续排查问题。
-- **继续已有工作**：保存项目会话，通过 `/resume` 恢复对话；支持上下文用量显示和摘要压缩。
-- **处理图文输入**：支持多行编辑、长文本粘贴、图片输入，以及草稿撤销和重做。
-
-## 快速开始
-
-需要 Node.js 22 或更新版本，以及所选模型服务的 API 密钥。
-
-```sh
-git clone https://github.com/sadgsk/Anti-trace.git
-cd Anti-trace
-npm install
-```
-
-将 [byok.example.json](byok.example.json) 复制为用户目录下的 `~/.anti-trace/profiles/local/configs/main.json`（请先创建目录），填写：
-
-- 连接的 API key 和服务地址。
-- 模型 ID、上下文窗口与输出上限。
-- `currentModel`：要使用的模型配置键。
-
-示例默认选择的 `main` 使用占位地址和模型 ID，需要替换后才能调用。配置完成后启动：
-
-```sh
-npm start
-```
-
-也可以在本机注册 `ati` 和 `anti-trace` 两个等价的启动命令。先在本仓库目录执行：
-
-```sh
-npm run build
-npm link
-```
-
-之后在任意工作目录运行 `ati` 或 `anti-trace`，程序会使用该目录作为 cwd，模型配置默认从用户目录加载。`CLI_AGENT_CONFIG` 可显式指定其他 JSON 文件。命令运行的是编译后的 `dist`；修改源码后重新执行 `npm run build` 即可，无需再次 link。`npm link` 只注册本地命令，不会发布到 npm。
-
-macOS／Linux 使用 Bash。Windows 优先使用 PowerShell（优先 7，回退到系统 5.1）；安装 Git for Windows 后还会提供 Git Bash，用于 Bash 脚本和 POSIX 命令。Git Bash 安装在特殊目录时，可在启动前设置 `ANTI_TRACE_GIT_BASH_PATH` 为其 `bin\bash.exe` 的绝对路径。可以从 CMD 或 PowerShell 启动 Anti-trace，工具执行器由程序独立选择。命令默认超时为 120 秒。
-
-进入对话后，可以直接描述任务，例如：
-
-```text
-梳理这个项目的入口和主要模块。
-修复这个函数对空输入的处理，并补上对应测试。
-运行构建，分析报错并修改相关代码。
-```
-
-Agent 会按任务需要读取文件、修改代码和执行命令。这些操作会直接影响项目文件，首次试用建议使用可恢复的项目副本。
-
-## 模型接入
-
-通过 BYOK JSON 配置自己的模型服务：
-
-| 接口 | 配置中的 api |
-|---|---|
-| OpenAI Chat Completions | `openai-completions` |
-| OpenAI Responses | `openai-responses` |
-| Anthropic Messages | `anthropic-messages` |
-
-模型通过 `connection` 引用连接配置，`currentModel` 选择 `models` 中的模型键。连接可以直接填写 `apiKey`，也可以用 `apiKeyEnv` 引用进程环境变量。
-
-CLI 使用统一的用户数据目录，默认是 `~/.anti-trace`，可通过 `ANTI_TRACE_HOME` 覆盖。模型配置保存在 `profiles/local/configs/`，`/config` 新建的文件也写入这里。`local` 是当前本地用户空间；代码通过 `profileId` 预留未来的用户隔离能力，当前没有登录功能。
-
-启动时依次使用：显式 `CLI_AGENT_CONFIG`、当前项目上次选择、当前用户默认选择、配置目录中唯一有效的配置。首次没有选择记录且存在多个配置时，需要通过 `/config` 选择。用户主动选择配置或模型后，会更新用户默认选择；打开已有项目不会用它的项目选择覆盖用户默认。不存在的记忆路径会提示并回退，显式路径错误会报错。不会自动读取工作目录的 `byok.json` 或 `.env`，也不读取旧目录的配置、偏好和会话。
-
-```text
-~/.anti-trace/
-├── preferences.json                     # 全局语言偏好
-└── profiles/local/
-    ├── configs/                         # 模型连接配置
-    ├── default-model.json               # 新项目的默认配置与模型
-    └── projects/<工作目录的 SHA-256>/
-        ├── project.json                 # 实际工作路径
-        ├── last-model.json              # 当前项目的配置与模型选择
-        ├── sessions/                    # 会话及图片附件
-        └── tool-results/                # 完整工具输出
-```
-
-选择记录只包含配置路径和模型键，不包含凭据。每个项目的会话和工具输出独立；语言偏好在本机共享。文件读写与 Shell 执行继续使用启动目录作为 cwd。临时图片转换文件使用系统临时目录。旧会话不迁移，原文件保留。
-
-Anthropic Messages 未填写 `maxOutputTokens` 时默认使用 `32000`；若配置的 `contextWindow` 更小，默认输出上限会降到窗口大小。显式填写的输出上限优先。
-
-`baseUrl` 应包含服务所需的版本前缀，例如 `/v1`。也可从 [厂商配置示例](byok.providers.example.json) 选取连接预设与模型，设置对应的环境变量密钥。示例覆盖九家厂商的 36 个连接选项；各协议、地区和模型的参数按明确规则适配。
-
-## 常用命令
-
-交互界面默认收起命令列表。输入 `/` 打开命令菜单，继续输入按名称筛选；↑↓ 选择，Enter 确认，Tab 仅补全，Esc 返回。模型、effort、思考及展示开关、会话恢复和配置管理使用二级界面，无需手输参数；原有显式参数仍兼容。输入框默认位于底部，滚轮和 PgUp／PgDn 回看历史，Ctrl+End 返回最新；Shift+拖动选中文本。
-
-| 命令 | 用途 |
-|---|---|
-| `/help` | 查看帮助 |
-| `/new` | 开始新会话 |
-| `/resume` | 方向键选择并恢复会话 |
-| `/model` | 从当前配置选择模型 |
-| `/config` | 配置文件菜单，同级新增／修改；同一文件新增多个模型，Enter 独立编辑字段 |
-| `/reload` | 重新读取模型配置 |
-| `/thinking` | 选择开启／关闭模型思考 |
-| `/effort` | 方向键选择 low／medium／high／xhigh／max |
-| `/thinking-display` | 选择开启／关闭思考文字默认展示 |
-| `/language` | 切换中文／English 界面，即时生效并记住偏好 |
-| `/context [正整数]` | 查看或调整上下文窗口 |
-| `/compact` | 尝试手动压缩上下文 |
-| `/exit` | 退出 |
-
-当前整体 TUI 已进入试用，交互与实现见 [架构文档](docs/architecture.md#4-分层)，验证和待办见 [开发进度](docs/progress.md)。支持 Markdown／代码／表格、工具卡与 Diff、权限审批、@ 文件补全和附件栏。Ctrl+O 在回看处原位展开／收起，在最新处定位并展开最近工具；Shift+Tab 切换权限模式。可用 `npm start -- --auto-edit` 或 `npm start -- --yolo` 显式指定启动模式。
-
-Enter 提交，Shift/Alt+Enter 或反斜杠后 Enter 换行；Ctrl+C 中断生成或清空草稿，空闲且草稿为空时退出。Ctrl+Z 撤销，Ctrl+Y 重做。快捷键识别取决于终端。
-
-`/reload` 重新读取模型配置，保留当前模型选择和思考偏好；`/new` 继承当前设置，`/resume` 从已加载目录解析会话保存的模型引用。思考显示开关只影响显示，不改变模型请求。
-
-## 项目方向
-
-项目目前处于早期开发阶段。长期目标是让用户用自然语言描述希望增加或修改的功能，由 agent 修改自身的工具、CLI 界面等能力，再通过热启动应用变更。
-
-这项能力尚未实现，顶部架构图展示的是预计设计。当前先完善模型接入、工具执行、会话与上下文管理等基础能力。
-
-- [ ] 根据自然语言需求动态修改工具、CLI 界面等功能。
-- [ ] 验证功能变更，并通过热启动加载修改。
-- [x] 厂商预设、思考控制与统一设置链路。
-- [ ] 在 v1.3 完善 TUI 交互。
-- [x] 建立可复现的离线测试框架和 Windows／Linux／macOS CI。
-- [ ] 扩展真实模型与原生终端验收。
-- [ ] 修复剩余的工具配对和上下文溢出提示问题。
-
-## 已知限制
-
-- Windows 需要可用的 PowerShell 或 Git Bash；没有 Git Bash 时只提供 PowerShell，显式配置的 Bash 路径无效时会提示配置错误。见 [问题记录](docs/future-issues.md)。
-- 可恢复的上下文溢出错误提前显示问题仍待处理；工具批次中断配对已在 TUI 批次修复，见 [评审记录](docs/review-records.md)。
-- 已有本地 HTTP SSE 和 macOS POSIX PTY 验证记录，真实模型、剪贴板和其他终端平台的覆盖仍不完整。
-- 正式测试位于 `tests/`。运行 `npm test` 执行离线测试，`npm run check` 执行类型检查、测试和构建；命令、覆盖范围与三端 CI 见 [测试指南](docs/testing.md)。真实模型检查使用独立的显式入口。
-
-## 开发文档与来源
-
-- [开发进度](docs/progress.md)：当前状态、待办与开发记录。
-- [架构书](docs/architecture.md)：模块职责与设计。
-- [测试与 CI](docs/testing.md)：本地命令、测试编写、隔离、覆盖率和三端 CI。
-- [关键认知](docs/key-points.md)：读码时形成的确定结论（工具字段位置、缓存前缀等），含原因与验证方式。
-
-项目从阅读和参考 [Pi](https://github.com/earendil-works/pi) 起步，部分基础代码参考并改写自 Pi，使用自己的 `Harness` 和功能设计，当前不依赖 Pi 的运行时包。
-
-## 许可证
-
-[MIT](LICENSE)。源自 Pi 的部分保留其原有版权和许可声明。
+# Anti-trace
+
+**中文** | [English](README.en.md)
+
+Anti-trace 是一个运行在终端里的 AI 编程 agent，可以帮你阅读和修改代码、执行 shell 命令、查找项目文件，并根据执行结果自主决定下一步动作。你可以使用自己的 API 密钥接入模型服务，目前支持 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages 三种接口。
+
+![Anti-trace 预计架构：现有 agent 基础与计划中的功能修改、验证和热启动流程（英文）](docs/assets/target-architecture.svg)
+
+## 能做什么
+
+- **理解项目**：阅读源码，梳理模块关系，解释代码逻辑。
+- **编写和修改代码**：根据需求实现功能、修复 bug、重构代码或编写文档。
+- **执行开发任务**：调用 shell 查找文件、运行构建和测试，并结合命令输出继续排查问题。
+- **继续已有工作**：保存项目会话，通过 `/resume` 恢复对话；支持上下文用量显示和摘要压缩。
+- **处理图文输入**：支持多行编辑、长文本粘贴、图片输入，以及草稿撤销和重做。
+
+## 快速开始
+
+需要 Node.js 22 或更新版本，以及所选模型服务的 API 密钥。
+
+```sh
+git clone https://github.com/sadgsk/Anti-trace.git
+cd Anti-trace
+npm install
+```
+
+将 [byok.example.json](byok.example.json) 复制为用户目录下的 `~/.anti-trace/profiles/local/configs/main.json`（请先创建目录），填写：
+
+- 连接的 API key 和服务地址。
+- 模型 ID、上下文窗口与输出上限。
+- `currentModel`：要使用的模型配置键。
+
+示例默认选择的 `main` 使用占位地址和模型 ID，需要替换后才能调用。配置完成后启动：
+
+```sh
+npm start
+```
+
+也可以在本机注册 `ati` 和 `anti-trace` 两个等价的启动命令。先在本仓库目录执行：
+
+```sh
+npm run build
+npm link
+```
+
+之后在任意工作目录运行 `ati` 或 `anti-trace`，程序会使用该目录作为 cwd，模型配置默认从用户目录加载。`CLI_AGENT_CONFIG` 可显式指定其他 JSON 文件。命令运行的是编译后的 `dist`；修改源码后重新执行 `npm run build` 即可，无需再次 link。`npm link` 只注册本地命令，不会发布到 npm。
+
+macOS／Linux 使用 Bash。Windows 优先使用 PowerShell（优先 7，回退到系统 5.1）；安装 Git for Windows 后还会提供 Git Bash，用于 Bash 脚本和 POSIX 命令。Git Bash 安装在特殊目录时，可在启动前设置 `ANTI_TRACE_GIT_BASH_PATH` 为其 `bin\bash.exe` 的绝对路径。可以从 CMD 或 PowerShell 启动 Anti-trace，工具执行器由程序独立选择。命令默认超时为 120 秒。
+
+进入对话后，可以直接描述任务，例如：
+
+```text
+梳理这个项目的入口和主要模块。
+修复这个函数对空输入的处理，并补上对应测试。
+运行构建，分析报错并修改相关代码。
+```
+
+Agent 会按任务需要读取文件、修改代码和执行命令。这些操作会直接影响项目文件，首次试用建议使用可恢复的项目副本。
+
+## 模型接入
+
+通过 BYOK JSON 配置自己的模型服务：
+
+| 接口 | 配置中的 api |
+|---|---|
+| OpenAI Chat Completions | `openai-completions` |
+| OpenAI Responses | `openai-responses` |
+| Anthropic Messages | `anthropic-messages` |
+
+模型通过 `connection` 引用连接配置，`currentModel` 选择 `models` 中的模型键。连接可以直接填写 `apiKey`，也可以用 `apiKeyEnv` 引用进程环境变量。
+
+CLI 使用统一的用户数据目录，默认是 `~/.anti-trace`，可通过 `ANTI_TRACE_HOME` 覆盖。模型配置保存在 `profiles/local/configs/`，`/config` 新建的文件也写入这里。`local` 是当前本地用户空间；代码通过 `profileId` 预留未来的用户隔离能力，当前没有登录功能。
+
+启动时依次使用：显式 `CLI_AGENT_CONFIG`、当前项目上次选择、当前用户默认选择、配置目录中唯一有效的配置。首次没有选择记录且存在多个配置时，需要通过 `/config` 选择。用户主动选择配置或模型后，会更新用户默认选择；打开已有项目不会用它的项目选择覆盖用户默认。不存在的记忆路径会提示并回退，显式路径错误会报错。不会自动读取工作目录的 `byok.json` 或 `.env`，也不读取旧目录的配置、偏好和会话。
+
+```text
+~/.anti-trace/
+├── preferences.json                     # 全局语言偏好
+└── profiles/local/
+    ├── configs/                         # 模型连接配置
+    ├── default-model.json               # 新项目的默认配置与模型
+    └── projects/<工作目录的 SHA-256>/
+        ├── project.json                 # 实际工作路径
+        ├── last-model.json              # 当前项目的配置与模型选择
+        ├── sessions/                    # 会话及图片附件
+        └── tool-results/                # 完整工具输出
+```
+
+选择记录只包含配置路径和模型键，不包含凭据。每个项目的会话和工具输出独立；语言偏好在本机共享。文件读写与 Shell 执行继续使用启动目录作为 cwd。临时图片转换文件使用系统临时目录。旧会话不迁移，原文件保留。
+
+Anthropic Messages 未填写 `maxOutputTokens` 时默认使用 `32000`；若配置的 `contextWindow` 更小，默认输出上限会降到窗口大小。显式填写的输出上限优先。
+
+`baseUrl` 应包含服务所需的版本前缀，例如 `/v1`。也可从 [厂商配置示例](byok.providers.example.json) 选取连接预设与模型，设置对应的环境变量密钥。示例覆盖九家厂商的 36 个连接选项；各协议、地区和模型的参数按明确规则适配。
+
+## 常用命令
+
+交互界面默认收起命令列表。输入 `/` 打开命令菜单，继续输入按名称筛选；↑↓ 选择，Enter 确认，Tab 仅补全，Esc 返回。模型、effort、思考及展示开关、会话恢复和配置管理使用二级界面，无需手输参数；原有显式参数仍兼容。输入框默认位于底部，滚轮和 PgUp／PgDn 回看历史，Ctrl+End 返回最新；Shift+拖动选中文本。
+
+| 命令 | 用途 |
+|---|---|
+| `/help` | 查看帮助 |
+| `/new` | 开始新会话 |
+| `/resume` | 方向键选择并恢复会话 |
+| `/model` | 从当前配置选择模型 |
+| `/config` | 配置文件菜单，同级新增／修改；同一文件新增多个模型，Enter 独立编辑字段 |
+| `/reload` | 重新读取模型配置 |
+| `/thinking` | 选择开启／关闭模型思考 |
+| `/effort` | 方向键选择 low／medium／high／xhigh／max |
+| `/thinking-display` | 选择开启／关闭思考文字默认展示 |
+| `/language` | 切换中文／English 界面，即时生效并记住偏好 |
+| `/context [正整数]` | 查看或调整上下文窗口 |
+| `/compact` | 尝试手动压缩上下文 |
+| `/exit` | 退出 |
+
+当前整体 TUI 已进入试用，交互与实现见 [架构文档](docs/architecture.md#4-分层)，验证和待办见 [开发进度](docs/progress.md)。支持 Markdown／代码／表格、工具卡与 Diff、权限审批、@ 文件补全和附件栏。Ctrl+O 在回看处原位展开／收起，在最新处定位并展开最近工具；Shift+Tab 切换权限模式。可用 `npm start -- --auto-edit` 或 `npm start -- --yolo` 显式指定启动模式。
+
+Enter 提交，Shift/Alt+Enter 或反斜杠后 Enter 换行；Ctrl+C 中断生成或清空草稿，空闲且草稿为空时退出。Ctrl+Z 撤销，Ctrl+Y 重做。快捷键识别取决于终端。
+
+`/reload` 重新读取模型配置，保留当前模型选择和思考偏好；`/new` 继承当前设置，`/resume` 从已加载目录解析会话保存的模型引用。思考显示开关只影响显示，不改变模型请求。
+
+## 项目方向
+
+项目目前处于早期开发阶段。长期目标是让用户用自然语言描述希望增加或修改的功能，由 agent 修改自身的工具、CLI 界面等能力，再通过热启动应用变更。
+
+这项能力尚未实现，顶部架构图展示的是预计设计。当前先完善模型接入、工具执行、会话与上下文管理等基础能力。
+
+- [ ] 根据自然语言需求动态修改工具、CLI 界面等功能。
+- [ ] 验证功能变更，并通过热启动加载修改。
+- [x] 厂商预设、思考控制与统一设置链路。
+- [ ] 在 v1.3 完善 TUI 交互。
+- [x] 建立可复现的离线测试框架和 Windows／Linux／macOS CI。
+- [ ] 扩展真实模型与原生终端验收。
+- [ ] 修复剩余的工具配对和上下文溢出提示问题。
+
+## 已知限制
+
+- Windows 需要可用的 PowerShell 或 Git Bash；没有 Git Bash 时只提供 PowerShell，显式配置的 Bash 路径无效时会提示配置错误。见 [问题记录](docs/future-issues.md)。
+- 可恢复的上下文溢出错误提前显示问题仍待处理；工具批次中断配对已在 TUI 批次修复，见 [评审记录](docs/review-records.md)。
+- 已有本地 HTTP SSE 和 macOS POSIX PTY 验证记录，真实模型、剪贴板和其他终端平台的覆盖仍不完整。
+- 正式测试位于 `tests/`。运行 `npm test` 执行离线测试，`npm run check` 执行类型检查、测试和构建；命令、覆盖范围与三端 CI 见 [测试指南](docs/testing.md)。真实模型检查使用独立的显式入口。
+
+## 开发文档与来源
+
+- [开发进度](docs/progress.md)：当前状态、待办与开发记录。
+- [架构书](docs/architecture.md)：模块职责与设计。
+- [测试与 CI](docs/testing.md)：本地命令、测试编写、隔离、覆盖率和三端 CI。
+- [npm 自动发布](docs/releases.md)：首次绑定 npm 与 GitHub，以及通过版本 tag 自动发布。
+- [关键认知](docs/key-points.md)：读码时形成的确定结论（工具字段位置、缓存前缀等），含原因与验证方式。
+
+项目从阅读和参考 [Pi](https://github.com/earendil-works/pi) 起步，部分基础代码参考并改写自 Pi，使用自己的 `Harness` 和功能设计，当前不依赖 Pi 的运行时包。
+
+## 许可证
+
+[MIT](LICENSE)。源自 Pi 的部分保留其原有版权和许可声明。