npm - @di-code/coding-agent - Versions diffs - 0.1.8 → 0.1.9 - Mend

@di-code/coding-agent 0.1.8 → 0.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +54 -625
package/package.json +9 -9

package/README.md CHANGED Viewed

@@ -1,675 +1,104 @@
 # @di-code/coding-agent
-`@di-code/coding-agent` 是 [di-code](https://github.com/qddidi/di-code) 的可安装终端 AI 编码代理。安装后提供：
+`@di-code/coding-agent` 是 di-code 的终端 AI 编码代理，提供以下命令：
-- `di-code`：面向人的交互式、单次输出、JSON 事件和本地 Web CLI（`di-code web`）；
-- `di-code-rpc`：供 Node.js 宿主程序管理的 JSONL RPC 子进程入口；
-- `di-code-webui`：本地 HTTP/SSE WebUI 传输入口；
-- 内置的 `read`、`write`、`edit`、`glob`、`grep`、`bash` 工具、JSONL 会话、图片输入、上下文压缩；
-- 可复用的 **Skills（技能指令）**、`AGENTS.md` 项目说明，以及插件扩展机制。
+- `di-code`：TUI 交互模式及单次、JSON 输出模式；
+- `di-code web`：本地浏览器 WebUI；
+- `di-code-webui`：供自定义客户端使用的 HTTP/SSE WebUI 传输层；
+- `di-code-rpc`：供 Node.js 宿主程序管理 Agent 的 JSONL RPC 入口。
-> **运行环境：**Node.js `>= 22.19.0`。真实 Provider 会产生网络请求和费用；首次体验可使用离线的 `faux` Provider。
-## 目录
-- [快速使用教程](#快速使用教程)
-- [配置模型 Provider](#配置模型-provider)
-- [日常使用](#日常使用)
-- [交互模式](#交互模式)
-- [会话、图片与内置工具](#会话图片与内置工具)
-- [项目说明与 Skills](#项目说明与-skills)
-- [插件](#插件)
-- [自定义 Provider](#自定义-provider)
-- [脚本和 RPC 集成](#脚本和-rpc-集成)
-- [安全边界与故障排查](#安全边界与故障排查)
-## 快速使用教程
-### 方式一：使用首次配置向导
-这是第一次使用时最简单的方式。先安装并进入项目目录：
+需要 Node.js `>=22.19.0`。已发布版本可直接安装：
 ```powershell
 npm install -g @di-code/coding-agent
 ```
-然后执行
-```
-di-code
-```
-在向导中依次完成：
-1. **选择 Provider**：例如 `OpenAI`、`Anthropic`、`DeepSeek`、`Zhipu AI`；也可以选择 `Custom` 配置兼容网关；如果只想离线试用，选择 `Faux (offline)`。
-2. **选择模型**：内建 Provider 会列出当前支持的模型；Custom 会先选择 API 协议，再输入 Base URL、API key 和任意模型 ID。
-3. **填写 API key**：选择真实 Provider 时，在隐藏输入框中粘贴对应的 key；输入内容不会显示在终端中。
-4. **确认并开始对话**：向导完成后进入 interactive 模式，在底部输入框输入问题并按 `Enter`。
+## WebUI 启动与设置
-向导输入的 API key 会保存到用户全局 `~/.di-code/settings.json`，供之后启动复用
-已经进入交互模式后，使用 `/login` 可以重新打开 Provider、模型和 key 向导。
-### 方式二：直接用 `settings.json` 配置
-如果你已经知道 Provider、`baseUrl`、模型和 API key，可以不使用向导，直接创建 `settings.json`。启动时会先读取用户全局配置 `~/.di-code/settings.json`，再读取当前项目的 `.di-code/settings.json`；项目配置会覆盖同名 Provider 的已设置字段，并保留全局 Provider 中项目未设置的字段。全局配置适合个人常用 Provider，项目配置适合私有网关或项目专用模型。
-同名 Provider 的 `models` 在项目中出现时会整体替换全局的模型列表；项目未写 `models` 时继续使用全局模型列表。只存在于任一文件中的 Provider 都会保留。
-下面这个例子使用 OpenAI Responses 兼容接口。将示例中的 `baseUrl`、`apiKey` 和模型字段替换为实际值后即可使用：
-`~/.di-code/settings.json` 或 `.di-code/settings.json`：
-```json
-{
-  "providers": {
-    "my-provider": {
-      "name": "My Coding Gateway",
-      "api": "openai-responses",
-      "baseUrl": "https://api.example.com/v1",
-      "apiKey": "your-api-key",
-      "models": [
-        {
-          "id": "my-coding-model",
-          "name": "My Coding Model",
-          "input": ["text", "image"],
-          "reasoning": true,
-          "contextWindow": 128000,
-          "maxTokens": 16384
-        }
-      ]
-    }
-  }
-}
-```
-默认使用第一个模型。可以添加多个模型然后使用`/model`切换
-`settings.json` 中的 `apiKey` 可以直接填写字符串，也可以引用环境变量。全局配置通常不进入项目 Git，因此适合保存个人配置；项目配置若使用明文 key，必须确保 `.di-code/settings.json` 不会提交。环境变量写法如下：
-```json
-{
-  "providers": {
-    "my-provider": {
-      "api": "openai-responses",
-      "baseUrl": "https://api.example.com/v1",
-      "apiKey": "$MY_CODING_API_KEY",
-      "models": [
-        {
-          "id": "my-coding-model",
-          "input": ["text"]
-        }
-      ]
-    }
-  }
-}
-```
+### 本地浏览器 WebUI
 ```powershell
-$env:MY_CODING_API_KEY = "your-api-key"
-$env:DI_CODE_PROVIDER = "my-provider"
-di-code "检查当前项目的测试状态"
-```
-`settings.json` 中最重要的字段是：
-| 字段 | 作用 |
-| --- | --- |
-| `providers` | Provider 配置对象，key 是 Provider ID |
-| `defaultProvider` | 可选的默认 Provider；`/login` 自动更新，多个 Provider 时用于消除启动歧义；项目值优先于用户级值 |
-| `defaultModel` | `defaultProvider` 的可选默认模型；`/login` 和 `/model` 自动更新；项目值优先于用户级值 |
-| `thinkingLevels` | 按 Provider 和模型保存的推理强度；项目值优先于同一用户级偏好 |
-| `locale` | 仅用户全局 `~/.di-code/settings.json`：`en` 或 `zh-CN`；控制内置 CLI 与交互终端文案 |
-| `permissionMode` | 仅用户全局 settings：`ask`、`allow` 或 `deny`；作为后续 Session 的工具权限默认值 |
-| `api` | 接口类型：`openai-responses`、`openai-chat-completions` 或 `anthropic-messages` |
-| `baseUrl` | Provider 的接口地址，必须是绝对的 `http` 或 `https` URL |
-| `apiKey` | API key，推荐填写 `$ENV_VAR` 或 `${ENV_VAR}` |
-| `models` | 自定义 Provider 必填的模型列表 |
-| `models[].id` | 模型真实 ID，也就是 `DI_CODE_MODEL` 的值 |
-| `models[].input` | 输入类型，填写 `text`、`image` 或两者 |
-| `models[].reasoning` | 是否支持 reasoning/thinking 内容 |
-| `models[].contextWindow` | 上下文 token 上限 |
-| `models[].maxTokens` | 单次最大输出 token 数，必须小于 `contextWindow`，以保留输入空间 |
-`models` 可以配置多个模型，运行时用 `/model` 切换，或者修改 `DI_CODE_MODEL`：
-```json
-{
-  "providers": {
-    "my-provider": {
-      "api": "openai-responses",
-      "baseUrl": "https://api.example.com/v1",
-      "apiKey": "$MY_CODING_API_KEY",
-      "models": [
-        { "id": "fast-model", "input": ["text"] },
-        { "id": "strong-model", "input": ["text", "image"], "reasoning": true }
-      ]
-    }
-  }
-}
+di-code web
 ```
-### 方式三：使用环境变量
-如果使用内建 Provider，可以只设置环境变量，不创建 `settings.json`：
+命令会启动只绑定本机回环地址的 Web server，并输出浏览器地址。可用 `--port` 指定端口，或用 `--workspace <path>` 添加已信任的工作区：
 ```powershell
-$env:DI_CODE_PROVIDER = "openai"
-$env:DI_CODE_MODEL = "gpt-4o"
-$env:OPENAI_API_KEY = "your-api-key"
-di-code --print "检查当前项目的目录结构"
+di-code web --port 4312 --workspace D:\projects\another-workspace
 ```
-确认 print 模式可以正常返回后，再运行 `di-code --interactive` 开始持续对话。
-## 配置模型 Provider
-日常使用推荐把凭据放在操作系统环境变量或未提交的项目 `.env` 中，**不要**把真实 API key 提交到 Git。全局安装的 `di-code` 读取当前进程环境变量；若使用项目 `.env`，请先通过你的 shell、秘密管理工具或启动脚本加载它。
+打开页面后，在 **Settings** 中选择 Provider、模型并完成 API key 配置。没有可用 Provider 时，WebUI 会先使用离线 Faux runtime，配置完成后再发起真实请求。浏览器只接收脱敏配置和不透明 ID，不会获得 API key。
-PowerShell 临时配置 OpenAI：
+从仓库源码启动：
 ```powershell
-$env:DI_CODE_PROVIDER = "openai"
-$env:DI_CODE_MODEL = "gpt-4o" # 可省略，使用该 Provider 的默认模型
-$env:OPENAI_API_KEY = "your-api-key"
-di-code "检查这个仓库的目录结构"
+npm install --ignore-scripts
+npm run build
+npm run dev -- web
 ```
-内建 Provider：
+完整的 WebUI 路由、开发代理、工作区授权和安全限制，见 [WebUI 使用指南](https://github.com/qddidi/di-code/tree/master/docs/webui/使用指南.md)。
-| Provider ID | 必需 API key 变量 | 可选 endpoint 覆盖变量 |
-| --- | --- | --- |
-| `openai` | `OPENAI_API_KEY` | `OPENAI_BASE_URL` |
-| `anthropic` | `ANTHROPIC_API_KEY` | `ANTHROPIC_BASE_URL` |
-| `deepseek` | `DEEPSEEK_API_KEY` | `DEEPSEEK_BASE_URL` |
-| `zhipu` | `ZAI_API_KEY` | `ZHIPU_BASE_URL` |
-| `kimi` | `KIMI_API_KEY` | `KIMI_BASE_URL` |
-| `faux` | 无 | 无（离线测试用） |
+### HTTP/SSE WebUI 传输层
-例如 DeepSeek：
+`di-code-webui` 面向嵌入式或自定义客户端，启动时必须提供至少 32 个字符的 token：
 ```powershell
-$env:DI_CODE_PROVIDER = "deepseek"
-$env:DI_CODE_MODEL = "deepseek-v4-flash"
-$env:DEEPSEEK_API_KEY = "your-api-key"
-di-code "找出可能需要补测试的模块"
-```
-`DI_CODE_MODEL` 必须属于当前 Provider；省略时会使用内建默认模型或该 Provider 列表中的第一个模型。选错模型时，CLI 会列出可用 ID。
-Kimi Coding 使用 OpenAI Chat Completions 兼容 endpoint `https://api.kimi.com/coding/v1`，内建模型为 `k3`、`k3-256k`、`kimi-for-coding` 和 `kimi-for-coding-highspeed`。Kimi 官方也提供 Anthropic 兼容 endpoint，但当前内建 Provider 使用 OpenAI 兼容协议。
-### 终端语言
-设置 `DI_CODE_LOCALE=zh-CN` 可为当前进程显示中文内置终端文案；`en` 则显示英文。未设置时，di-code 读取用户全局 `~/.di-code/settings.json` 的 `locale`，默认 `en`。在 interactive 模式中通过 `/settings` 切换会立即刷新界面并保存该全局偏好。项目 `.di-code/settings.json` 不会覆盖语言偏好。
-JSON/RPC 字段、slash command 名称、工具名、Provider 和模型 ID，以及插件提供的文本不随 locale 改变。
-## 日常使用
-```text
-Usage: di-code [options] <prompt>
-Options:
-  -p, --print        只输出最终 assistant 文本（默认）
-  --mode <mode>      输出模式：print、json 或 interactive
-  --interactive      启动交互式终端模式
-  --continue, -c     继续最近修改的会话
-  --session <path>   创建或恢复 JSONL 会话（相对工作根目录）
-  --image <path>     附加本地图片；可重复传入
-  --skill <path>     加载一个 SKILL.md 文件或技能目录；可重复传入
-  --no-skills        不加载任何 Skill
-  --no-context-files 不发现或加载 AGENTS.md
-  --trust-project    信任当前项目的本地 Skills 和插件
-  --untrust-project  撤销当前项目的本地信任
-  plugin <action>    安装、列出、启用、禁用、更新或移除插件
-  -h, --help         显示帮助
-  -v, --version      显示版本
+$env:DI_CODE_PROVIDER = "faux"
+$env:DI_CODE_WEBUI_PORT = "8787"
+$env:DI_CODE_WEBUI_TOKEN = "replace-with-a-random-token-of-at-least-32-characters"
+di-code-webui
 ```
-### 三种输出模式
-| 模式 | 适合场景 | 示例 |
-| --- | --- | --- |
-| `print`（默认） | 单次提问、shell 调用；stdout 只有最终文本 | `di-code "解释 package.json"` |
-| `json` | 脚本或其他程序消费流式事件；每行一个 JSON 记录 | `di-code --mode json "运行测试并总结结果"` |
-| `interactive` | 长时间结对编码、查看流式输出与工具状态 | `di-code --interactive` |
-常用示例：
-```powershell
-# 只获得最终回答；错误写入 stderr，成功退出码为 0
-di-code --print "列出主要模块及其职责"
-# JSONL 事件流。不要把这个模式的 stdout 当作普通文本解析
-di-code --mode json "检查 TypeScript 配置"
-# 显式进入持续对话
-di-code --interactive
-# 使用一个指定、可持续追加的会话
-di-code --session .di-code\sessions\review.jsonl "审查当前改动"
-di-code --session .di-code\sessions\review.jsonl "继续处理最高优先级问题"
-# 恢复最近修改的会话
-di-code --continue "继续上一次工作"
-```
-`--help` 和 `--version` 必须单独使用。非交互模式必须有 prompt；`--continue` 不能和 `--session` 一起使用；`--print` 不能和 `--mode json` 或 interactive 模式组合。
-## 交互模式
-运行 `di-code` 或 `di-code --interactive` 后，在底部输入框输入请求并按 `Enter`。生成过程中输入的新请求会排队，按顺序执行。
-### 自定义 TUI Host
-第三方 ANSI TUI 可通过 `@di-code/coding-agent/ui-host` API v1 替换 composition 中的 `interactive-host`，而无需复制 Provider、MCP、Skills、JSONL Session 或 Agent loop bootstrap。entry 使用 `createUiHostEntry()` 注册自己的 UI 生命周期；回调获得的 `UiHost.session` 提供 prompt、取消、retry、受管 Session 切换、树和压缩，`UiHost.product` 只提供只读资源快照、主题/键位注册和脱敏诊断。它不暴露 `commandRegistry` 任意执行器，也不提供 HTTP/SSE WebUI 或新的 RPC 方法。
-回调必须持续到 UI 退出，并监听传入的 `AbortSignal`。正常退出、取消、抛错或 composition dispose 时，产品会取消并等待 Session 操作、释放 MCP/Session 资源，再使 facade 失效；之后访问 facade 会得到 `UiHostLifecycleError`（`DISPOSED`）。Session 操作错误通过稳定 code 表示，例如 `BUSY`、`INVALID_INPUT`、`NOT_FOUND` 和 `SESSION_IN_USE`。自定义 TUI 与所有插件一样运行在同一 Node.js 进程中，manifest `permissions` 仅供声明和审计，并不是操作系统级沙箱。完整 package、composition patch 和生命周期示例见 [插件使用指南](../../docs/插件使用指南.md#自定义-tui-host)。
-### Slash commands 与快捷键
-输入 `/` 后可补全命令；补全菜单打开时按 `Enter` 会直接运行当前选中的 slash command，按 `Tab` 只补全到输入框。
-| 命令 | 作用 |
-| --- | --- |
-| `/help` | 显示可用交互命令 |
-| `/clear` | 仅清除屏幕可见消息，不删除会话文件 |
-| `/model` | 切换当前 Provider 的模型 |
-| `/session` | 选择或切换会话 |
-| `/tree` | 打开当前历史对话分支树；可以选择回退至哪个阶段 |
-| `/theme` | 选择 dark 或 light 主题 |
-| `/settings` | 配置上下文压缩开关和内置终端语言 |
-| `/login` | 打开 Provider、模型和隐藏 API key 向导；保存到用户全局配置并切换当前会话 |
-| `/logout` | 移除当前 Provider 的用户全局 `apiKey`，并在适用时清除默认 Provider/模型；不改环境变量或其他 Provider 配置，当前会话保持可用至退出 |
-| `/compact` | 立即压缩当前持久化会话的旧上下文 |
-| `/usage` | 查看请求数、token、费用和上下文占用 |
-| `/retry` | 重新提交最近失败或取消的 prompt |
-| `/steer` | 在当前 prompt 运行期间向 Agent 追加引导内容（例如 `/steer 简短回答`）；空闲时使用会报错 |
-| `/skill:<name>` | 手动调用一个已加载的 Skill，可附带具体请求（见下文 Skills 部分） |
-插件和扩展也可以注册额外 slash command，名称与内置命令冲突时以加载诊断为准。
-| 按键 | 作用 |
-| --- | --- |
-| `Enter` | 发送当前 prompt |
-| `Shift+Enter` | 在输入框中插入换行 |
-| `Esc` | 取消当前模型请求并显示取消状态；没有请求时关闭补全或选择器 |
-| `Ctrl+C` | 退出并恢复终端状态 |
-| `Tab` | 补全 slash command |
-| `Alt+S` | 把编辑框当前内容作为引导发送给运行中的 Agent（与 `/steer` 等价） |
-| `Shift+Tab` | 循环切换模型的 thinking 等级并保存为用户偏好（模型不支持时提示错误） |
-| `Ctrl+O` / `Ctrl+L` | 打开模型 / 会话选择器 |
-| `Ctrl+T` / `Ctrl+S` | 打开主题 / 设置 |
-| `Ctrl+R` | 重试最近失败的 prompt |
-取消只停止当前请求，不会删除已经追加到磁盘的会话记录，并显示取消状态而非错误。之后可使用 `/retry` 再试一次。
-## 会话、图片与内置工具
-### 会话
-交互式启动默认会在用户目录 `~/.di-code/sessions/<工作区哈希>/` 创建 v2 JSONL 会话。记录为 append-only（只追加）格式，可引用任意已提交父节点，因此一份文件可以保存多个分支；重启默认恢复物理文件末端记录所在的分支。`/tree` 只在 interactive 模式提供专用树浏览器：以紧凑单栏树显示节点摘要和当前路径，当前选择以 `›` 标识；选择用户消息会将其文本恢复到编辑器，并从它的父节点创建新的 sibling 分支；选择 assistant、tool result 或 summary 则将该节点作为活动叶节点。`s` 会在所选路径上执行现有上下文压缩，成功后的 summary 成为下一条 prompt 的分支父节点；手动压缩在“保留最近 token”配置覆盖整段历史时仍会保留最新完整用户回合并压缩更早历史，只有没有可压缩的早期回合时才会明确失败。图片附件不会自动恢复，导航只改变模型可见上下文，不能回滚工作区副作用。v1 或未知版本的会话文件不迁移，打开时返回 `UNSUPPORTED_VERSION`。完整磁盘历史和发送给模型的压缩上下文分开保存，summary 只作用于其所在分支。`/session` 与 `--continue` 只显示或恢复当前工作区的默认会话；`--session` 可以打开任意指定路径。已有项目内 `.di-code/sessions/` 文件不会自动移动，仍可用 `--session <path>` 显式打开。
-产品 interactive 与 RPC 会话都由 Composition 的 `AgentSessionFactory` 创建。factory 为每个会话建立 isolated Context，并从当时已激活的 `ToolRegistry` 与 capability services 固定工具快照；禁用或未加载的工具不会被会话补回。interactive 的 JSONL 持久化通过 `SessionStoreRegistry` 的 `jsonl` entry 创建或打开，不能绕过 registry 直接在宿主启动分支中组装 Session。直接构造 `AgentSession` 必须传入不可变 `tools` 快照；SDK 集成应使用 Composition factory 或自行从其注册表创建该快照。
-产品层内部 `SessionHost`/`SessionActor` 会集中拥有 Session、MCP、工具快照、事件订阅和 requestId 操作表；每个 actor 按 principal 与真实 workspace 隔离。它使用 opaque Session ID 解析受管 JSONL 文件，并在重复打开时返回稳定的所有权冲突。失败或取消的 prompt 会以 host 私有 plugin record 绑定 request ID 和文本；因此 RPC `retry(targetRequestId)` 在关闭再打开同一 Session 后仍会选择同一个失败 turn，而不会猜测“最后一条消息”。Host 的 `dispose()` 与 `AgentSession.dispose()` 都是幂等的，会先结束或取消活跃操作，再释放 listener、子 Context、锁和 MCP 连接。内建 interactive TUI 通过私有 `UiHost` facade 使用这些能力；该 facade 不是 WebUI、RPC 或第三方公开契约。
-会话可能包含你的 prompt、模型回答、工具结果和图片内容。不要在 prompt 或图片中提交不应保留在本地历史中的密钥或敏感材料。
-### 图片
-非交互模式使用 `--image`，可重复传入：
-```powershell
-di-code --image .\diagram.png "解释这张架构图"
-di-code --image .\before.png --image .\after.webp "比较两张图"
-```
-只支持 PNG、JPEG、WebP、GIF；文件根据内容签名而不是扩展名校验。每条 prompt 最多 4 张、每张最多 5 MiB，并且当前模型必须声明支持图片输入。
-交互模式中可输入 `@diagram.png`；有空格的路径使用 `@"architecture diagram.png"`。也可将图片拖入终端。读取剪贴板图片时，Windows 使用 `Alt+V`，macOS/Linux 使用 `Ctrl+V`。剪贴板临时文件放在用户目录 `~/.di-code/clipboard/<工作区哈希>/<进程 ID>/`，发送、删除引用或退出后会清理；启动时也会清理当前工作区超过 24 小时的遗留文件。
-### Agent 可调用的内置工具
-模型可按任务需要调用以下工具；请在可信项目中运行，并在 prompt 中明确希望它执行或不执行的动作。
-| 工具 | 功能 | 限制 |
-| --- | --- | --- |
-| `read` | 读取工作根目录中的 UTF-8 文本文件 | 最多 2,000 行、50 KiB；支持 `offset`、`limit` |
-| `write` | 创建或完全覆盖 UTF-8 文件 | 自动创建父目录 |
-| `edit` | 对文件做一次唯一的精确文本替换 | 找不到或匹配多处时拒绝写入；保留 BOM 和换行风格 |
-| `glob` | 按 glob pattern 查找文件 | 返回排序后的相对路径；默认最多 200 个结果、50 KiB；跳过 symlink |
-| `grep` | 在 UTF-8 文本文件中查找字面量文本 | 返回 `path:line` 匹配；默认最多 200 个结果、50 KiB；跳过二进制文件、symlink 和超过 2 MiB 的单文件 |
-| `bash` | 在工作根目录执行本地命令 | 默认 30 秒、最大 5 分钟；stdout/stderr 各截断至 50 KiB |
-文件工具限制目标在工作根目录内并拒绝二进制文件。`glob` 和 `grep` 使用 Node 文件 API，不依赖系统安装的 `grep` 或 shell；它们不跟随 symlink，并支持取消信号。`grep` 的 `pattern` 是字面量匹配，不是正则表达式。`bash` 在 Windows 使用 PowerShell，在其他平台使用 `/bin/sh`；它并不是操作系统级沙箱。模型和插件仍可能尝试执行危险操作，因此请审查任务和结果，并避免在包含无关敏感文件的目录运行。
-## MCP Server
-受信任项目可在工作根目录创建 `.mcp.json` 来接入 MCP Server tools。支持本地 `stdio` 和远程 Streamable HTTP：
-```json
-{
-  "mcpServers": {
-    "project-tools": { "command": "npx", "args": ["-y", "@example/project-mcp"] }
-  }
-}
-```
-HTTP 配置使用 `type: "http"`、绝对 `http`/`https` `url` 和可选 `headers`。Server ID 使用小写字母、数字、`-` 和 `_`；工具名会转换为 `mcp__project-tools__<tool-name>`。支持 resources/prompts 的 Server 还会显式注册 `mcp__project-tools__resources_list`、`resource_read`、`prompts_list` 和 `prompt_get`；资源和提示词不会自动注入模型上下文。`env` 和 `headers` 中可使用 `${ENV_VAR}`，缺失变量会阻止该配置加载且不会泄露变量值。项目未获 trust 时不会启动 local/project Server；user scope 仍可使用。连接、schema、认证或工具调用错误会产生脱敏 `mcp_diagnostic` 或正常的工具错误。MCP Server 是外部代码，项目 trust 不是权限沙箱。
-配置管理命令：
-```powershell
-di-code mcp add project-tools -- npx -y @example/project-mcp
-di-code mcp add --scope project project-tools -- npx -y @example/project-mcp
-di-code mcp add --scope project --transport http company-api https://mcp.example.com/mcp
-di-code mcp list --scope project
-di-code mcp get company-api
-di-code mcp remove company-api --scope project
-```
-配置范围按 `local` > `project` > `user` 生效：local 写入 `<work-root>/.di-code/mcp.local.json`，project 写入 `<work-root>/.mcp.json`，user 写入 `~/.di-code/mcp.json`。同一 Server ID 整体覆盖，不做字段级合并。interactive 启动时，每个 MCP Server 会先显示黄色 `[loading]`，并在完成时原位替换为绿色 `[ok]` 或红色 `[error]`；成功状态包含 tools、resources 和 prompts 数量，失败信息经过脱敏。`McpTransportRegistry` 注册 stdio 和 Streamable HTTP factory，MCP client entry 追踪其 Fiber 创建的所有 manager，并在 interactive 退出、启动失败或 composition dispose 时幂等关闭连接。`mcp add <id> -- <command> [args...]` 默认使用 local stdio；HTTP 必须显式指定 `--transport http`。`list` 和 `get` 会脱敏 header、环境变量和其他凭据；`add` 不安装或下载 Server 软件，stdio 的命令仍由用户提供并在连接时执行。
-## 项目说明与 Skills
+默认只绑定 `127.0.0.1`。远程访问还需要显式设置 `DI_CODE_WEBUI_ALLOW_REMOTE=1` 并配置可信 Origin。客户端认证方式、SSE 恢复和完整环境变量见 [WebUI 使用指南](https://github.com/qddidi/di-code/tree/master/docs/webui/使用指南.md)。
-### `AGENTS.md`：给 Agent 的项目规则
+## TUI 启动与向导配置
-启动时，di-code 会读取全局 Agent 目录中的 `AGENTS.md`（或 `AGENTS.MD`），以及当前工作目录中的同名文件。不会自动加载当前目录父级中的 `AGENTS.md`。这些文件会作为项目上下文提供给模型，适合记录构建命令、代码风格、测试要求和目录约定。
+### 启动交互式 TUI
-项目文件是**不可信的上下文**，不能改变 CLI 的真实路径、权限或安全边界。临时忽略所有这类文件：
+安装后直接运行：
 ```powershell
-di-code --no-context-files "只分析当前文件，不遵循项目说明"
-```
-### Skills：可按需加载的专业工作流
-Skill 是带 YAML frontmatter 的 `SKILL.md` 文件。解析、发现、目录和正文读取由独立的 `@di-code/skills` 包提供；它不是可执行代码。默认情况下，模型只看到名称和描述；任务匹配时，它必须使用受控的 `load_skill` 工具按名称加载正文。
-Skill 的发现位置和优先级如下：
-1. `--skill <path>` 显式传入的文件或目录；
-2. 已信任项目的 `.di-code/skills/` 与 `.agents/skills/`；
-3. 用户全局目录 `~/.di-code/skills/`。
-目录会递归查找名为 `SKILL.md` 的文件，跳过隐藏目录和 `node_modules`。同名时先发现的 Skill 生效；冲突和格式错误会产生诊断。项目 Skill 不会在项目未信任时加载。Skill metadata 不能授予文件、命令或网络权限。
-创建项目 Skill：
-```text
-my-project/
-  .di-code/
-    skills/
-      release-check/
-        SKILL.md
-```
-`.di-code/skills/release-check/SKILL.md`（或 `.agents/skills/release-check/SKILL.md`）：
-```markdown
----
-name: release-check
-description: Verify the release checklist before publishing a package.
----
-1. Read the unreleased changelog section.
-2. Run the project test command before any release action.
-3. Report failures; never publish unless the user explicitly asks.
-```
-规则：
-- `name` 必填，最长 64 个字符，只能使用小写字母、数字和单连字符；
-- `description` 必填，最长 1,024 个字符；
-- 文件最大 256 KiB，首行和 frontmatter 结束行必须都是 `---`；
-- 可加 `disable-model-invocation: true` 隐藏该 Skill，使模型不自动选择它，但用户仍可手动调用。
-交互式 TTY 首次发现项目本地 Skill、插件或扩展目录时，di-code 会询问是否信任当前项目。回答 `y`/`yes` 会加载这些项目资源，其他输入（包括直接回车）会拒绝加载；选择会保存到用户全局 Agent 目录，后续启动不再重复询问。非交互模式不会等待询问，默认不信任。
-也可以显式授予信任：
-```powershell
-Set-Location D:\work\my-project
-di-code --trust-project --interactive
-```
-撤销：
-```powershell
-di-code --untrust-project --interactive
-```
-手动选择一个已加载 Skill 的语法为 `/skill:<name> [你的具体请求]`，可在普通 prompt 或交互输入框中使用：
-```powershell
-di-code "/skill:release-check 检查这个仓库是否已经满足发布前置条件"
-```
-或临时加载不属于项目目录的 Skill：
-```powershell
-di-code --skill D:\team-skills\release-check "按 release-check 流程检查"
-di-code --no-skills "不要加载任何 Skill"
-```
-> Skill 是提示词上下文，不是权限机制。只把可信、准确的 Skill 放入全局目录或授予项目信任；Skill 中提及的相对路径以该 Skill 所在目录为基准。
-## 插件
-插件是与 di-code 运行在**同一 Node.js 进程**中的 JavaScript/TypeScript namespace module。Provider、Agent、工具、Session、CLI/TUI、RPC、MCP 和 Skills 都以 Composition entry 装配；第三方 entry 可以在公开 runtime/registry 边界贡献服务、工具、命令、renderer 或事件观察者。
-发布插件必须在 `package.json.diCode.plugins` 中只列出一个 package `exports` entry。namespace 必须导出非空 `name` 和 `apply`，不能有 `default` export；`apiVersion` 若存在必须为 `1`，`version` 若存在必须是合法标识。Loader 只解析 enabled managed package；disabled package 不会 import。required entry 失败会回滚已经 active 的 entry 并阻止启动，optional entry 失败会成为 `skipped` inventory。完整 package shape、SDK、Composition、trust、capability 和 lifecycle 规则见[插件使用指南](../../docs/插件使用指南.md)。
-插件不是 MCP Server，也没有热重载、插件市场或真正的权限沙箱。manifest 的 `permissions` 是声明和 capability audit 信息，**不会**阻止插件访问文件、网络或子进程。因此，只安装可信来源的插件。`--trace-plugins` 可显示实际 phase 和失败诊断。
-### 管理全局插件
-全局托管插件安装在用户的 `~/.di-code/plugins/installed/` 下，只有已启用的插件会在启动时加载：
-```powershell
-# 本地目录、npm 包或 git URL 都可以作为来源
-di-code plugin install D:\work\my-plugin
-di-code plugin install npm:@acme/di-code-project-status@1.0.0
-di-code plugin install git:https://github.com/acme/di-code-project-status.git
-# 查看 ID、启用状态和版本
-di-code plugin list
-di-code plugin get project-status
-di-code plugin disable project-status
-di-code plugin enable project-status
-di-code plugin update project-status
-di-code plugin remove project-status
-```
-安装过程固定使用 `npm --ignore-scripts`，但这并不使插件本身安全：插件在加载时仍是本机代码。`plugin` 管理命令不需要配置 Provider。
-默认运行时先加载 `base` composition，再加载 `interactive`、`print`、`json` 或 `rpc` entry 集合，并追加所有 enabled managed package entry。`--profile <print|json|interactive>` 选择 CLI profile；`--composition <path>` 将一个 JSON 或 YAML document 作为最后一层应用，固定优先级为 `base -> mode -> ~/.di-code/composition.yml -> <work-root>/.di-code/composition.yml -> --composition`。项目 composition 仅在该项目已被 `--trust-project` 信任时读取；`--no-project-plugins` 会为当前运行跳过它，但不会禁用用户托管插件。RPC 使用同一 trust 规则：未信任项目不会读取其 composition，但仍加载用户已启用的受管 package。缺失的 user/project 文件会忽略，格式错误或显式文件不可读取则终止启动并显示路径。`plugin-manager` 是一个 command plugin，管理操作不会 import 已禁用插件。嵌入产品仍可直接使用 `@di-code/plugin-loader` 的公开 API。需要诊断 composition 时可运行：
-```powershell
-di-code --trace-plugins
-di-code --dump-composition
-```
-两条命令按需挂载 `plugin-trace` 和 `plugin-dump-composition`，输出实际 resolved tree、entry phase、owner Fiber、capability audit 与脱敏失败信息；不会输出 entry config、安装路径、凭据或完整 Provider 请求。
-## 自定义 Provider
-在 interactive TTY 的首次向导或 `/login` 中选择 `Custom`，可以按协议、Base URL、API key 和模型 ID 的顺序配置一个用户级固定 `custom` Provider。支持 `openai-responses`、`openai-chat-completions` 和 `anthropic-messages`。Base URL 必须是绝对 `http`/`https` URL，不能包含凭据、query、hash 或尾随 `/`。如果模型 ID 与内置目录中的同协议模型精确匹配，向导会复制其能力元数据；否则使用保守的文本模型默认值。重新配置会覆盖 `custom`，但保留其他用户级 Provider。
-自定义 OpenAI Responses 兼容网关或私有模型时，可在用户全局 `~/.di-code/settings.json` 或工作根目录 `.di-code/settings.json` 中声明 Provider。两个文件同时存在时，项目配置覆盖全局配置中的同名 Provider 字段。`apiKey` 可以直接填写，或使用环境变量引用：
-```json
-{
-  "providers": {
-    "company-gateway": {
-      "name": "Company Gateway",
-      "api": "openai-responses",
-      "baseUrl": "https://gateway.example.com/v1",
-      "apiKey": "$COMPANY_GATEWAY_API_KEY",
-      "models": [
-        {
-          "id": "company-coder",
-          "name": "Company Coder",
-          "input": ["text", "image"],
-          "reasoning": true,
-          "contextWindow": 200000,
-          "maxTokens": 32000
-        }
-      ]
-    }
-  }
-}
-```
-然后设置 Provider、模型和凭据：
-```powershell
-$env:COMPANY_GATEWAY_API_KEY = "your-api-key"
-$env:DI_CODE_PROVIDER = "company-gateway"
-$env:DI_CODE_MODEL = "company-coder"
-di-code "总结当前项目"
+di-code
 ```
-`api` 可为 `openai-responses`、`openai-chat-completions` 或 `anthropic-messages`。自定义 Provider 必须提供 `models`；每个模型可设置 `id`、`name`、`input`、`reasoning`、`reasoningEfforts`、`defaultReasoningEffort`、`contextWindow`、`maxTokens`（或 `maxOutputTokens`）及按美元/百万 token 计的 `cost`。`defaultReasoningEffort` 必须在 `reasoningEfforts` 中。Chat Completions 模型还可声明 `chatCompletionsCompat`，用于 DeepSeek/GLM/Kimi 的 thinking、reasoning_effort、`max_tokens`、流式 usage 和 `tool_stream` 等兼容差异。Kimi 模型支持 `low`、`high`、`max` 推理等级；Kimi 不发送 DeepSeek/智谱的 `thinking` 对象，而是发送 `reasoning_effort`。
-`apiKey` 支持直接字符串，也支持 `$NAME` 或 `${NAME}` 环境变量引用。项目级 `settings.json` 若含明文 key，必须保持未提交；`baseUrl` 必须是绝对 `http`/`https` URL。
-## 脚本和 RPC 集成
-### 处理 CLI 退出码
-脚本中可根据退出码处理结果：`0` 表示成功，`1` 表示参数错误、Provider 未配置或运行失败。print 模式的最终回答写 stdout；错误写 stderr，避免混入回答。
+也可以显式指定交互模式：
 ```powershell
-di-code --print "生成变更摘要"
-if ($LASTEXITCODE -ne 0) {
-  throw "di-code failed with exit code $LASTEXITCODE"
-}
+di-code --interactive
 ```
-JSON 模式的 stdout 是逐行版本化事件，适合流式消费：
+从仓库源码运行：
 ```powershell
-di-code --mode json "检查测试状态" | ForEach-Object {
-  $event = $_ | ConvertFrom-Json
-  # 根据 $event.type 处理事件
-}
+npm run dev
+# 或
+npm run dev -- --interactive
 ```
-### JSONL RPC
-`di-code-rpc` 是供宿主程序启动的子进程入口，不是交互命令。它从 stdin 接收一行一个 JSON 请求，并从 stdout 写一行一个版本化响应或事件；stderr 仅用于诊断。
-worker 由 composition 的 `session-factory` 创建 session，并由同一 composition 的 `rpc-server` entry 创建和拥有 `RpcServer`；入口本身只等待该 service。stdin 结束或收到终止信号时，它会先结束或取消活跃请求并写入终态 response，再 flush stdout、dispose composition，最后退出。嵌入 `RpcServer` 时，使用可 await 的 `shutdown()` 获得同一顺序；`stop()` 保留为兼容的非阻塞入口。
-公开 RPC 方法：
-| 方法 | 参数 | 结果 |
-| --- | --- | --- |
-| `get_state` | `{}` | Session ID、模型、是否正在生成、消息数 |
-| `prompt` | `{ "message": "..." }` | 最终 `AssistantMessage`，中间事件另行输出 |
-| `cancel` | `{ "requestId": "..." }` | 是否找到并取消该请求 |
-`RpcServer` 是 JSONL 传输适配器；协议解析、参数校验、方法分发、操作表和事件恢复由无 stdin/stdout 依赖的 `RpcDispatcher` 完成。嵌入其他传输时只能复用 dispatcher，不得让网络写入等待 Agent 事件处理。
-新客户端先调用 `get_capabilities` 并在 `events` 中声明 `sequence`、`operation_update`、`snapshot_required` 等扩展事件。未协商的连接只接收原有 Agent 事件，因此旧客户端不会遇到未知 event。协商后可调用 `list_sessions`、`new_session`、`open_session`、`get_transcript`、`get_tree`、`navigate_tree`、`steer`、`retry`、`get_operation`、模型/运行时、压缩、usage 和资源快照方法，以及 `list_commands` 和 `run_command`。前者只返回当前 composition 注册的命令和当前 Session 已加载的 Skills；后者只接受清单中已注册的命令名与字符串参数，`args` 可以为空，扩展命令仍在其 registry handler 中运行。`set_runtime` 和 `set_thinking_level` 都会在空闲时更新当前 Session，并持久化为之后 WebUI Session 与终端启动使用的默认模型/推理偏好；已有工作区 `.di-code/settings.json` 时写入工作区，否则写入用户级 settings。若终端显式设置了 `DI_CODE_PROVIDER` 或 `DI_CODE_MODEL`，环境变量仍优先。`set_thinking_level` 传入 `level: "low" | "medium" | "high" | "max"` 时按值设置；省略 `level` 保持原有循环行为。异步请求由 request ID 归属；重复同一 ID 返回同一个操作结果，`get_operation` 可查询 detached 操作，`cancel` 可取消它。事件带可选 `sessionId` 和单调 `sequence`，`resume_events` 在环形缓冲已过期时发送 `snapshot_required`，客户端必须重新读取状态、transcript、tree 和 usage。
-v1 只新增方法与可选字段。产品配置、附件、工具审批和插件命名空间仍要求对应的显式 Host capability、schema、权限和 owner disposer；没有这些能力的 composition 会以 `METHOD_NOT_FOUND` 拒绝。`run_command` 是唯一的命令投影：它只执行同一 composition 中已注册且由 `list_commands` 返回的名称，浏览器不会取得 registry 或调用任意插件代码。
-Node.js 宿主从公开入口导入 SDK：
-```ts
-import { RpcClient, RPC_PROTOCOL_VERSION } from "@di-code/coding-agent/rpc";
-```
-`RpcClient` 和 `RpcSupervisor` 提供类型化的状态、prompt/steer/retry/cancel、Session 列表/切换、transcript/tree、模型、压缩、
-operation、附件，以及 Provider、项目 trust、context file 和 MCP 配置 facade；`call()` 只保留给已协商的低层方法。`login()` 的
-API key 只在请求中传递，返回值、事件、Session 和诊断均不包含它。MCP 或 trust 配置成功后，Host 会在空闲状态刷新当前 Session 的
-Skills、context 和 MCP 工具快照；生成或压缩期间会以 `BUSY` 拒绝这类变更。
-附件先经 `createAttachment(name, contentType, base64Data)` 上传，再将返回 ID 传给 `prompt(message, { attachmentIds })`。只接受
-PNG、JPEG、WebP、GIF，每次请求最多 4 个、每个最多 5 MiB；WebUI 将数据保存到每个 client/actor 独立的受管附件目录，
-并在首次 prompt/steer 使用、超时或 Host dispose 时删除；JSONL RPC 没有附件目录时使用同样限制的进程内存存储。
-SDK 不自动重放任何请求，即使子进程退出或事件恢复失败也不例外；调用方必须使用新的 request ID 明确发起重试。
-事件订阅使用 `subscribe()`。调用 `negotiate(["sequence", "operation_update", "snapshot_required", "product_audit"])` 后，保存收到记录的
-`sequence`，并在重连后通过 `resumeEvents(lastSequence)` 恢复。返回 `snapshotRequired: true` 时，重新读取 state、transcript、tree
-和 usage，而不要推测遗漏的事件。所有 response、event、error code 和 version 都在 SDK JSONL 边界验证；未知事件或不符合 v1
-形状的记录会关闭 client 并拒绝 pending request。
-RPC client 也有独立的 `rpc-client-sdk` namespace composition entry；嵌入式宿主可以从 `@di-code/coding-agent/rpc-client-sdk` 导入其 `rpcClientSdkKey`，由 Loader 创建 `RpcClient`。`runtime-core`、`composition-loader` 和 `project-trust` 同样提供独立 entry，分别拥有运行时服务、Loader factory 和 trust store 服务。
-需要监督子进程生命周期时，使用 `@di-code/orchestrator`，不要依赖 coding-agent 的内部文件路径。
-### WebUI HTTP/SSE
-`di-code web` 将助手回复渲染为 GitHub Flavored Markdown；嵌入 HTML 不解析，也不会执行。
-`di-code web [--port <0-65535>]` 是面向浏览器的同源入口，默认使用随机可用端口并且始终只绑定 `127.0.0.1`。同一个 Node 进程拥有静态 SPA、`GET /healthz`、`GET /api/boot` 和现有 HTTP/SSE RPC adapter 的 `/api` 路由；页面只读取 boot/capabilities，实际 prompt、Session 和工具调用仍由 `RpcDispatcher`/`SessionHost` 执行。静态资源来自已安装包的 `dist/web`，API 路由与 SPA fallback 隔离，路径穿越和 symlink 逃逸会被拒绝。首次静态页面响应建立 HttpOnly、SameSite cookie，浏览器不需要知道 transport token。
-`npm run web:dev` 是源码开发 supervisor：它保留现有 Provider/settings 环境、等待 backend 的真实随机端口、再启动 Vite 代理；若当前 Provider 尚未配置 API key，则 backend 使用 Faux runtime 启动页面，供用户在 Settings 中完成登录，内置 Provider（包括 Zhipu）仍会显示为未配置状态，settings 文件本身的格式或安全校验错误仍会失败。端口冲突会失败，`Ctrl+C` 会终止 backend 和 Vite。它只供本地开发，不能用于远程 bind 或放宽 workspace 授权。
-Web SPA 的首页读取 `/api/boot`、`list_sessions` 和脱敏 `get_settings` 快照，提供双栏导航、workspace 选择、受管 Session 创建/打开、响应式侧栏，以及拆分为 General/Models 的 Settings overlay。启动时的真实 workspace 与重复 `--workspace` 显式授权且已信任的 workspace 会以不透明 ID 返回，选择后只显示该 workspace 的会话；会话按最后修改时间倒序。侧栏的 `Add workspace` 支持系统目录选择器和将文件夹直接拖入；目录校验通过后立即加入授权列表并切换到该 workspace。工作区行悬停时显示更多与新建会话图标，更多菜单可改名或删除（启动工作区不可删除）。取消选择不会改变当前 workspace。每个 workspace actor 的工具边界使用该 workspace 自身根目录，切换后模型不会继续访问启动目录。设置快照中的每个模型会包含其实际支持的 `reasoningEfforts`；活动 Provider 即使未注册到全局目录也会作为运行时回退返回。对话 store 以 `get_state`、完整 transcript 和 usage snapshot 为权威，消费有序 SSE 来投影 streaming text、thinking、operation 与 usage；重连使用 resume token，收到 `snapshot_required` 或刷新后完整重拉，绝不静默重放 prompt。新建会话会先在列表中显示占位项，首条用户消息生成标题后再替换。图片和文本都作为 durable user message 保存；Web transcript 将持久化图片映射为 data URL 并在对应用户消息中渲染。为读取最大 5 MiB 图片的 base64 JSONL 记录，`get_transcript.maxBytes` 上限为 8 MiB。每个 transcript 消息同时携带 durable entry ID；从完成回复创建分支时，RPC 会以该 entry ID 截断后续上下文、打开新分支并返回其 active session。composer 支持输入法组合、拖放/粘贴/文件选择图片、最多四个 opaque attachment handle、运行时 steer、cancel 和失败 retry。PNG/JPEG/WebP/GIF 单张图片可达 5 MiB，base64 传输按附件上限而非普通 prompt 长度校验，并作为 Provider context 的 image content block 传递。仅模型目录声明 `input: ["text", "image"]` 时，composer 才允许附加图片；文本模型不能静默发送空图片。OpenAI Chat Completions 兼容 Provider 会把用户图片映射为标准的 `image_url` data URL content part。浏览器内仅有预览 object URL；服务端路径、transport token、Provider key 不会出现在页面、事件或错误中。配置中心只接受窄参数 RPC：Provider 登录/登出、自定义 Provider、运行时模型和推理强度、默认 Provider/model、locale 和权限模式；已有工作区 settings 时模型与推理强度保存到工作区，否则保存到用户级 settings。环境变量托管字段只读显示，API key 不会出现在快照、事件或错误中。外观切换仅作用于浏览器本地页面。
-Web composer 的 Commands 菜单和输入开头的 `/` 都会显示当前 composition 的内置、扩展命令和已加载的 `/skill:<name>`；选择不需要参数的内置或扩展 command 会立即通过 `run_command` 执行，只有 `/skill:<name>` 和 `/steer` 会写入输入框以补充请求内容。`/tree` 打开 Session 树节点弹窗，同一线性分支保持左对齐，只有实际分叉才增加缩进；选择 user 节点会回填其文本并从父节点继续，选择完成的 assistant、tool result 或 summary 节点会从所选节点继续。带 tool call 的中间 assistant 节点不可选择，应选择对应 tool result。树导航不会回滚已经发生的工作区副作用。Web transcript 遇到持久化的显式 Skill 展开消息时，只展示 Skill 名称，不展示其展开正文。
-对话区的 `Chat`/`Trajectory` tabs 直接消费 `tool_execution_start/end`、`compaction_*`、`usage_update` 和 `tool_approval` 事件。空闲时的 `Compact context` 控制项调用现有 `compact` RPC，生成或压缩期间会禁用。工具卡为 `read`、`write`、`edit`、`bash`、`glob`、`grep` 保留独立状态和折叠输出，edit 结果的 `details.diff/patch` 以纯文本代码块显示；长输出不会注入 HTML。`ask` 模式的审批使用服务端生成的 `approvalId`，浏览器通过 `approve_tool` 回传决定，不能绕过 Agent 的工具校验。
-`di-code-webui` 是给自定义或嵌入式 HTTP 客户端保留的 token header transport：
-`di-code-webui` 使用 `webui` composition 创建 `HostManager` 和每个浏览器 client 的 `SessionActor`，再由 `RpcDispatcher` 执行所有 RPC v1
-方法。它通过 `list_commands`/`run_command` 受控投影同一 composition 已注册的命令，不向浏览器暴露 `commandRegistry` 或任意命令执行入口，也不会创建第二个 Agent loop。Web 与 TUI 使用同一套环境变量、工作区和用户级 settings 解析 Provider、模型、语言、thinking 默认值和持久化 Session；client/actor 目录只保存附件等传输临时状态，不能承载 settings 或 Session。设置 `DI_CODE_WEBUI_TOKEN` 为至少 32 个字符的随机值后启动；默认绑定
-`127.0.0.1` 和随机可用端口，可用 `DI_CODE_WEBUI_PORT` 指定端口。`DI_CODE_WEBUI_HOST` 只有与 `DI_CODE_WEBUI_ALLOW_REMOTE=1` 同时设置时才可绑定非回环地址。
-`POST /rpc`、`GET /events` 和 `POST /attachments` 都要求 `Authorization: Bearer <token>` 或 `X-Di-Code-Token` header。服务拒绝不匹配的
-Host、Origin、token、工作区和超限请求；默认只授权启动时的真实 workspace。每个 client 的持久化 Session 与附件 storage 分离，不能通过 opaque
-Session 或 attachment ID 访问其他 client 的数据。`WebUiServer.rotateToken()` 和 `revokeToken()` 会关闭现有 SSE 订阅并使旧 token 立即失效。
-SSE 的 `ready` 数据提供 10 分钟有效的 `resumeToken`；每次成功恢复都会轮换 token，旧值立即失效。每个带 sequence 的事件也使用 SSE `id` 字段。空闲连接每 15 秒发送一次 SSE comment keepalive；默认最多 8 个 SSE 连接/浏览器 client、64 个/服务进程，超限返回 `429`。重连以
-`X-Di-Code-Resume-Token` 和 `Last-Event-ID` headers 恢复事件。重放窗口不足时会收到
-`snapshot_required`，调用方必须重新读取 state、transcript、tree 和 usage。连接关闭不会取消 detached operation；使用 `get_operation` 查询，只有
-`cancel` 会取消。终态 operation 默认保留 10 分钟且最多 256 条，过期或超出上限后 `get_operation` 返回 `NOT_FOUND`。附件通过 JSON base64
-上传，限制为 PNG/JPEG/WebP/GIF、每个 5 MiB、每 client 32 个或 64 MiB、TTL 10 分钟，保存在 actor 受管目录中并在首次 prompt/steer
-使用、过期或 Host dispose 后删除。
-ProductHost 的 login/logout、项目 trust 和 MCP 配置均作为可取消的 detached operation 执行；Session 正在生成或压缩时会返回 `BUSY`。协商 `product_audit` 后，成功变更会发送仅含动作、Provider/MCP 标识或 trust 状态的审计事件，绝不包含 API key 或配置 secret。
-WebUI 不是沙箱。认证客户端能触发当前 workspace 内的文件和 shell 工具，远程绑定等同于向 token 持有者开放这些能力；不要把 token、Provider
-凭据或 attachment 内容记录到 URL、事件、日志或错误文本。
-仓库示例 [`examples/webui-client.ts`](../../examples/webui-client.ts) 只使用 HTTP/SSE 公开字段，覆盖完整的最小客户端流程。运行前先构建并以
-`DI_CODE_PROVIDER=faux`、固定 `DI_CODE_WEBUI_PORT` 和至少 32 字符的 `DI_CODE_WEBUI_TOKEN` 启动 `di-code-webui`。自定义 ANSI TUI 的已测试 fixture
-位于 [`test/fixtures/custom-tui.ts`](test/fixtures/custom-tui.ts)，只从 `@di-code/coding-agent/ui-host` 和 `@di-code/tui` 导入；它通过 composition
-替换 `interactive-host`，不复制 Session、MCP 或 Agent bootstrap。
+### 首次 Provider 向导
-## 安全边界与故障排查
+在真实 TTY 中启动，且没有 `DI_CODE_PROVIDER`、默认 Provider 或唯一已配置 Provider 时，会自动打开向导。向导依次让你：
-- 在可信项目根目录运行；`bash` 不是沙箱，插件也没有沙箱。
-- 向导会将输入的 API key 保存到用户全局 `~/.di-code/settings.json`；不要放入 prompt、Skill、插件源码、会话、图片、项目配置或 Git。
-- 项目 Skill 和 MCP 配置默认不加载；交互式 TTY 首次发现这些内容时会询问一次，`--trust-project` / `--untrust-project` 可显式控制。该决定不会导入旧项目本地插件目录，也不会赋予额外系统权限。
-- Provider、模型、图片、配置和工具参数都会校验；外部项目内容和模型输出仍应视作不可信输入。
+1. 选择 Provider（选择 `Faux (offline)` 可离线试用）；
+2. 选择模型；
+3. 输入 API key（隐藏显示）；
+4. 对 `Custom` Provider 填写 API 协议、Base URL 和模型 ID。
-| 问题 | 优先检查 |
-| --- | --- |
-| `Provider is not configured` | 设置 `DI_CODE_PROVIDER` 及对应 API key；或在 TTY 中运行 `di-code` 使用向导；离线测试使用 `faux` |
-| `Unknown model` | 确认 `DI_CODE_MODEL` 属于当前 `DI_CODE_PROVIDER` |
-| 项目 Skill / MCP 没有加载 | Skill 目录是否为 `.di-code/skills` 或 `.agents/skills`，或检查 `.mcp.json`；交互式启动时确认 trust 提示，或运行 `di-code --trust-project --interactive` |
-| `Unknown skill` | Skill 是否有正确 `SKILL.md` frontmatter，名称是否匹配 `/skill:<name>`；检查是否被 `--no-skills` 禁用 |
-| plugin Loader 诊断 | 检查 `package.json.diCode.plugins`、对应 `exports`、namespace `name`/`apply` 与 `di-code --dump-composition` 输出；详见插件指南 |
-| 图片被拒绝 | 确认格式、4 张/5 MiB 限制，以及模型 `input` 包含 `image` |
-| 文件工具无法访问路径 | 从工作根目录启动，且目标未越出根目录；二进制文件不支持 |
+向导会把选择保存到用户级 `~/.di-code/settings.json`，下次启动自动复用。交互模式中可用 `/login` 重新打开向导。非交互的 `--print`、JSON 和 CI 运行不会启动向导，应提前设置环境变量或 settings；Provider、模型和 `settings.json` 字段说明见 [CLI 与配置](https://github.com/qddidi/di-code/tree/master/docs/用户指南/CLI与配置.md)。
-## 相关链接
+## 完整文档
-- 项目源码与完整开发文档：<https://github.com/qddidi/di-code>
-- 插件详细指南：[GitHub 上的《插件使用指南》](https://github.com/qddidi/di-code/blob/main/docs/%E6%8F%92%E4%BB%B6%E4%BD%BF%E7%94%A8%E6%8C%87%E5%8D%97.md)
-- 问题反馈：<https://github.com/qddidi/di-code/issues>
-- 许可证：[MIT](https://github.com/qddidi/di-code/blob/main/LICENSE)
-WebUI 高级设置通过 RPC v1 暴露 `list_plugins` 与可取消的 `set_plugin_enabled`；Skills、MCP、Trust 和配置快照沿用现有窄方法，不提供任意命令执行入口。插件权限仅用于声明和审计，Workspace trust 只影响项目本地 Skills、MCP 与 composition 加载。
+README 只保留最短启动路径，其他功能请按主题阅读 GitHub `docs`：
-Web 插件扩展通过新增的 `list_web_contributions` RPC 返回 version `1` 的声明式 manifest。宿主只按白名单 `componentKey` 映射 `app.sidebar`、`session.tree`、`conversation.node`、`conversation.tool` 和 `settings.panel` slot；插件命令、任意 URL/HTML/JS 和完整 dispatcher 不会进入浏览器。贡献按 `order` 稳定排序并绑定 owner disposer，Workspace 未信任时不暴露项目插件 Web 声明；插件失败或卸载只影响其 slot，不影响 Agent loop、Session 或核心页面。
+- [文档索引](https://github.com/qddidi/di-code/tree/master/docs)
+- [快速开始](https://github.com/qddidi/di-code/tree/master/docs/用户指南/快速开始.md)
+- [CLI 与配置](https://github.com/qddidi/di-code/tree/master/docs/用户指南/CLI与配置.md)
+- [会话、Skills 与图片](https://github.com/qddidi/di-code/tree/master/docs/用户指南/会话与Skills.md)
+- [MCP 使用指南](https://github.com/qddidi/di-code/tree/master/docs/用户指南/MCP.md)
+- [WebUI 自定义 UI](https://github.com/qddidi/di-code/tree/master/docs/webui/自定义UI.md)
+- [自定义 Web 前端开发](https://github.com/qddidi/di-code/tree/master/docs/webui/自定义前端.md)
+- [TUI 使用指南](https://github.com/qddidi/di-code/tree/master/docs/tui/使用指南.md)
+- [插件使用指南](https://github.com/qddidi/di-code/tree/master/docs/插件使用指南.md)
+- [开发教程](https://github.com/qddidi/di-code/tree/master/docs/开发教程.md)
+- [运行时与 RPC 架构](https://github.com/qddidi/di-code/tree/master/docs/架构/运行时与RPC.md)

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
 	"name": "@di-code/coding-agent",
-	"version": "0.1.8",
+	"version": "0.1.9",
 	"description": "Coding agent product layer for di-code",
 	"keywords": [
 		"ai-coding-agent",
@@ -130,14 +130,14 @@
 		"test": "vitest run --passWithNoTests"
 	},
 	"dependencies": {
-		"@di-code/agent": "0.1.8",
-		"@di-code/ai": "0.1.8",
-		"@di-code/builtins": "0.1.8",
-		"@di-code/mcp": "0.1.8",
-		"@di-code/plugin-loader": "0.1.8",
-		"@di-code/plugin-runtime": "0.1.8",
-		"@di-code/skills": "0.1.8",
-		"@di-code/tui": "0.1.8",
+		"@di-code/agent": "0.1.9",
+		"@di-code/ai": "0.1.9",
+		"@di-code/builtins": "0.1.9",
+		"@di-code/mcp": "0.1.9",
+		"@di-code/plugin-loader": "0.1.9",
+		"@di-code/plugin-runtime": "0.1.9",
+		"@di-code/skills": "0.1.9",
+		"@di-code/tui": "0.1.9",
 		"diff": "8.0.4",
 		"highlight.js": "^10.7.3",
 		"jiti": "^2.5.1"