@sortedyuan/maybecode 0.3.2 → 0.5.0

package/README.md

@@ -1,5 +1,112 @@
 # MaybeCode
 
+[简体中文](README.zh-CN.md)
+
+MaybeCode is a coding agent for reading projects, searching files and text,
+editing code, running commands, and consulting web documentation. It provides
+a retained terminal interface, a Web UI, resumable sessions, and delegated teams.
+
+## Requirements
+
+Use Node.js **22.16 or newer**. Container execution additionally requires
+Docker Desktop or a compatible Docker runtime with a running daemon.
+
+## Installation
+
+Install the published package globally with npm or pnpm:
+
+```sh
+npm install --global @sortedyuan/maybecode
+pnpm add --global @sortedyuan/maybecode
+```
+
+## Configure a model
+
+Save this minimal configuration as `may.config.json` in your project. Set
+`DEEPSEEK_API_KEY` in your environment to your provider API key.
+
+```json
+{
+  "providers": {
+    "deepseek": { "adapter": "deepseek-chat", "apiKeyEnv": "DEEPSEEK_API_KEY" }
+  },
+  "models": {
+    "deepseek": { "provider": "deepseek", "model": "deepseek-chat" }
+  },
+  "defaultModel": "deepseek"
+}
+```
+
+## Start
+
+```sh
+maybecode --config may.config.json .
+maybecode --help
+```
+
+`--ui` accepts `retained` (the default) and `web`. Run `/web` from the terminal
+to open a connected browser view. Web-only startup requires
+`MAYBECODE_CONTROL_TOKEN`; see [Web UI](#web-ui-developer-preview).
+
+## Resume a session
+
+```sh
+maybecode --config may.config.json --continue .
+maybecode --config may.config.json --resume <session-id> .
+```
+
+Ordinary startup creates a new session. `/resume` opens the session picker;
+saved sessions remain available across restarts.
+
+## Approval modes
+
+Normal mode approves `read`, `glob`, and `grep` automatically. Commands, edits,
+writes, and `fetch` web requests require approval. `fetch` has a separate network
+permission category, including persistent rules when enabled.
+`--yolo` enables automatic approval; `--no-yolo` selects normal mode. Explicit
+policy denials remain enforced. `/yolo on|off|status` controls the running host.
+
+## Execution isolation
+
+`apps.maybecode.execution` defaults to `{ "mode": "host" }`. Host commands run
+with your account's permissions. To execute commands in a container, pull an
+image before startup and configure the same image:
+
+```sh
+docker pull nixery.dev/shell/git/ripgrep/util-linux
+```
+
+```json
+{
+  "apps": {
+    "maybecode": {
+      "execution": {
+        "mode": "container",
+        "image": "nixery.dev/shell/git/ripgrep/util-linux",
+        "network": "none",
+        "memoryBytes": 1073741824,
+        "cpuCount": 2
+      }
+    }
+  }
+}
+```
+
+The image must contain `bash`, `git`, `rg`, and `setsid`. Container execution
+uses a non-root user, a read-only root filesystem, temporary `/tmp` storage,
+disabled networking, and the configured memory and CPU limits. Only the workspace
+is mounted. File tools access the same workspace from the host. Shell, search,
+delegated tools, and authorized team checks use the configured execution environment.
+MCP servers continue to run on the host. Missing Docker service or images stop
+startup. Closing the application waits for its execution resources to terminate.
+
+The `fetch` tool accesses public HTTP/HTTPS origins by default. Configure
+`apps.maybecode.fetch.allowedOrigins` to restrict requests to specific origins;
+listed origins may explicitly permit local services. `maxBytes`, `timeoutMs`,
+and `maxRedirects` bound responses. Redirect destinations are checked individually.
+
+## Delegation notifications
+
 Automatic request and task status notices are disabled by default. Use
 `/delegations notifications on|off|status` to change or inspect the current
 process setting, including during a run. Set `apps.maybecode.delegationNotifications`
@@ -17,7 +124,7 @@ recreated; MaybeCode refreshes its service references and event subscriptions.
 Conversation history, paused Goals, active Skills, durable notes and the current
 permission mode remain available. Shared MCP connections remain open.
 
-Headless hosts can call `MaybeCodeApplication.updateModel()` with a Model,
+Headless hosts can call `controller.application.updateModel()` with a Model,
 `modelInfo`, and optional `modelRuntimeOptions` and `contextBudget`. A configured
 Model plugin retains ownership of model selection. `modelUpdateFailed` reports an
 unsuccessful update; new input remains unavailable until an update succeeds.
@@ -82,11 +189,11 @@ apply to the current workspace host and all its sessions and connected views;
 they do not update configuration. Restarting uses the current startup settings.
 
 The terminal status bar and Web UI header show `YOLO · Auto-approve` while enabled.
-Classic terminal mode shows it in the input prompt. Notifications use `YOLO enabled`
+Notifications use `YOLO enabled`
 and `YOLO disabled`. Explicit policy denials remain enforced. Tool validation,
 cancellation, execution records, and MCP requests for user-provided input remain
-active. Shell commands run with the host account's OS permissions; YOLO provides
-no filesystem or network isolation. Team commands retain their own authorization.
+active. Shell commands use the configured execution environment. YOLO changes
+approval behavior. Team commands retain their own authorization.
 
 ### Persistent permission rules
 
@@ -119,7 +226,7 @@ process exit. See [Permission policies](../../docs/en/guides/permission-policy.m
 and [权限策略](../../docs/zh-CN/guides/permission-policy.md).
 
 Image replies retain text/image ordering. Terminal saves embedded images and
-supports Kitty/iTerm2/Sixel graphics in both terminal frontends; `/web` provides
+supports Kitty/iTerm2/Sixel graphics in the terminal frontend; `/web` provides
 image viewing and downloads. Windows Terminal is detected through `WT_SESSION`
 and queried for Sixel support and cell dimensions. `MAY_IMAGE_PROTOCOL=sixel`
 explicitly selects Sixel for a compatible terminal.
@@ -128,7 +235,7 @@ See [Image replies](../../docs/en/guides/images.md) /
 
 `/goal start [--max-runs N] [--tokens N] [--duration-ms N] -- <objective>` starts a
 durable goal. Use `/goal status`, `/goal pause`, `/goal resume` and `/goal cancel`
-in either terminal frontend or the Web UI. New user input pauses active goals.
+in the terminal frontend or the Web UI. New user input pauses active goals.
 Run count and active execution time have no default limits; the corresponding
 flags apply only when specified. Saved goals retain their recorded budgets.
 See [Goals](../../docs/en/guides/goals.md) and
@@ -136,7 +243,7 @@ See [Goals](../../docs/en/guides/goals.md) and
 
 MaybeCode is a coding-agent application assembled from May's Core, application,
 session, permission, provider, configuration, coding-tool and UI packages.
-It offers terminal frontends and a developer-preview Web UI.
+It offers a terminal frontend and a developer-preview Web UI.
 
 In the retained TUI, the mouse wheel scrolls the conversation by three rows per
 event while preserving editor focus and draft text. Scrolling up keeps the
@@ -155,7 +262,7 @@ sessions and for replies longer than the normal scroll buffer.
 
 ## Web UI (developer preview)
 
-Type `/web` in either terminal frontend to open the current workspace and Session
+Type `/web` in the terminal frontend to open the current workspace and Session
 in the default browser. The terminal shares live output, approvals, model selection
 and Session changes with the Web UI. Repeating `/web` opens the same service with
 a fresh one-time connection link. No token environment variable is needed. After
@@ -204,8 +311,8 @@ or [简体中文指南](../../docs/zh-CN/guides/web-ui.md) for commands and curr
 
 `src/plugins/application.ts` defines application features and service selection;
 `src/plugins/resources.ts` defines workspace resource ownership and the shared
-MCP and tracing providers supplied to each Session. `MaybeCodeApplication.open`
-and `openConfiguredMaybeCode` use these factories directly.
+MCP and tracing providers supplied to each Session. `openConfiguredMaybeCode`
+uses these factories directly.
 
 MaybeCode selects Model, Context, Permission, Skills, Goals, History Memory,
 Delegation, and Workspace Files plugins for each application. Optional MCP and
@@ -215,7 +322,7 @@ connections. Each worktree owns its configured MCP connections and stdio working
 directories; returning to a workspace reuses them. All workspaces share the tracing
 processor. Closing the host releases every workspace connection and the processor.
 
-`MaybeCodeApplication.open({ plugins, ... })` accepts custom plugins. A selected
+`openConfiguredMaybeCode({ plugins, ... })` accepts custom plugins. A selected
 plugin replaces a default with the same id or provided service token; the host
 validates the complete dependency graph. `goals: false`, `subagents: false`, and
 `skills: false` retain their independent disable controls. Configured MCP and
@@ -245,8 +352,8 @@ continue to re-export history-memory and delegation interfaces.
 MaybeCode is a product composition layer. Generic lifecycle does not live in
 the app:
 
-- `@sortedyuan/core`'s instance-scoped `ToolRegistry` composes the coding tools;
-- `@sortedyuan/application`'s `defineAgent()` captures reusable behavior, while its
+- `@sortedyuan/may/core`'s instance-scoped `ToolRegistry` composes the coding tools;
+- `@sortedyuan/may`'s `defineAgent()` captures reusable behavior, while its
   application/workspace layer owns run/retry/cancel, approval relaying,
   Session history, Context compaction persistence, closing, session switching,
   and Catalog summaries;
@@ -279,9 +386,9 @@ also requires passing acceptance. `team verify <id>` explicitly runs checks;
 status and recovery never replay them.
 
 `--mode coding` allows explicitly listed editing tools in private task copies.
-`--allow-checks` separately authorizes exact configured test processes, not a
-general model-controlled Shell. These processes are **not OS-sandboxed**, even
-for a read-only team. MCP and model-controlled source application stay disabled.
+`--allow-checks` separately authorizes exact configured test processes. Checks
+inherit `apps.maybecode.execution`, including container restrictions when selected.
+MCP and model-controlled source application stay disabled.
 `team diff <id> --tasks <task-ids>` exports a reviewable patch; only
 `team apply <id> --patch <patch-id> --confirm <digest>` can apply it after human
 review. Another task's passing checks never verify an unchecked patch task.
@@ -295,6 +402,7 @@ resets budgets. Existing v1 teams keep their original read-only
 `resume`/`status`/`cancel` behavior without a silent authority upgrade.
 
 Guides:
+
 - Teams: [English](../../docs/en/guides/maybecode-team.md) / [简体中文](../../docs/zh-CN/guides/maybecode-team.md)
 - Plans: [English](../../docs/en/guides/maybecode-team-plan.md) / [简体中文](../../docs/zh-CN/guides/maybecode-team-plan.md)
 - Verification: [English](../../docs/en/guides/maybecode-team-verification.md) / [简体中文](../../docs/zh-CN/guides/maybecode-team-verification.md)
@@ -308,38 +416,40 @@ or remote UI sends user actions through its methods and renders its
 `AsyncIterable<MaybeCodeEvent>` stream:
 
 ```ts
-import {
-  openConfiguredMaybeCode,
-  type MaybeCodeController,
-} from "@sortedyuan/maybecode";
+import { openConfiguredMaybeCode, type MaybeCodeController } from "@sortedyuan/maybecode";
 
-const controller: MaybeCodeController = await openConfiguredMaybeCode();
+const controller: MaybeCodeController = await openConfiguredMaybeCode({
+  configPath: "may.config.json",
+});
 
 const observation = (async () => {
   for await (const event of controller.events) {
-    render(event);
+    console.log(event);
   }
 })();
 
-await (await controller.submit({ input: "Inspect this workspace." })).result;
-await controller.close();
-await observation;
+try {
+  console.log(controller.application.modelInfo);
+  await (
+    await controller.submit({ input: "Inspect this workspace." })
+  ).result;
+} finally {
+  await controller.close();
+  await observation;
+}
 ```
 
-The controller covers submission, cancellation, approvals, sessions, history,
-session rename/deletion, and context inspection/compaction.
-`MaybeCodeWorkspace` is the default concrete
-implementation. `MaybeCodeTerminal` is only the low-level input/output adapter
-for the bundled `runTerminalUI`; implementing it changes terminal mechanics but
-does not replace the bundled UI's command or rendering policy.
-
-Custom UIs can reuse the bundled command policy without reusing the terminal
-renderer. `MAYBECODE_SLASH_COMMANDS` exposes command metadata,
-`createMaybeCodeSlashCommandSuggester(controller)` provides command, compaction
-strategy, and session suggestions, and
-`executeMaybeCodeSlashCommand(input, controller)` returns a structured result
-for the UI to render. Alternatively, a UI can call `MaybeCodeController`
-directly and define a completely different command system.
+The controller covers submission, steering, cancellation, approvals, sessions,
+history, session rename/deletion, and context inspection/compaction.
+`controller.application` is the application of the active Session; read its
+state there, for example `application.getGoal()`, `application.modelInfo`,
+`application.instructions`, `application.listSkills()` and
+`application.getDelegationState()`. A Session change replaces it, so read it again
+after switching. `controller.transition(action)` runs a state change on the
+Session queue of the active application. The package exports only
+`runMaybeCode`, `openConfiguredMaybeCode`, `MaybeCodeController` with its event
+types, and `MaybeCodeUsageError`; a custom UI defines its own command system on
+top of the controller.
 
 Ordinary input submitted during execution cancels the current operation, waits
 for its cancellation to finish, and starts the new input in the same Session.
@@ -352,17 +462,15 @@ inputs in order after the active operation finishes.
 `/stop`, the Web cancel control, and `Ctrl+C` without a text selection cancel the
 current operation and every queued input. Cancelled steering inputs remain in
 history and are not submitted again automatically. To use one later, explicitly
-send the message again. These rules apply to both terminal frontends, Web UI,
-and `MaybeCodeWorkspace.submit()` / `steer()`. General `AgentApplication.submit()`
+send the message again. These rules apply to the terminal frontend, Web UI,
+and `MaybeCodeController.submit()` / `steer()`. General `AgentApplication.submit()`
 continues to require that the application has no active operation.
 
 The bundled SessionPicker uses the optional `@sortedyuan/keybindings` package to map
 context-specific key sequences to semantic actions. Custom UIs may reuse that
 resolver or provide their own keyboard and interaction system.
 
-The retained-screen frontend is the default. The previous line-oriented
-frontend remains available with `maybecode --ui classic [workspace]`. The
-retained frontend supports Slash-command completion and a `/resume` dialog with search (`/`),
+The retained-screen frontend is the default terminal frontend. It supports Slash-command completion and a `/resume` dialog with search (`/`),
 rename (`r`), delete (`d`), and resume (`Enter`) actions. It also renders safe
 terminal Markdown and uses specialized, collapsible renderers for `read`,
 `shell`, `edit`, and `write`.
@@ -676,9 +784,8 @@ See the [instruction composition guide](../../docs/en/guides/maybecode-instructi
 or its [Chinese version](../../docs/zh-CN/guides/maybecode-instructions.md).
 
 Programmatic callers can pass a `ContextFactory` to
-`openConfiguredMaybeCode`, `MaybeCodeWorkspace.open`, or
-`MaybeCodeApplication.open`. When omitted, MaybeCode uses
-`InMemoryContextFactory` from `@sortedyuan/context`. Factories return the Core context
+`openConfiguredMaybeCode`. When omitted, MaybeCode uses
+`InMemoryContextFactory` from `@sortedyuan/may/context`. Factories return the Core context
 and may also return a `ContextController` for application-level inspection.
 
 ## Commands
@@ -697,6 +804,12 @@ their original input; `/recovery resolve <id> <verified finding>` records the
 result of checking external effects. No tool is replayed by recovery. See
 [Crash recovery](../../docs/en/guides/recovery.md).
 
+The retained TUI and Web history display saved recovery findings as user messages.
+Web history search and full-field reads include their complete text. Both views
+preserve denied, not-started, and unknown tool outcomes and interrupted partial
+assistant replies. Web commands validate current execution and Session ownership
+independently from presentation reads such as workspace details and fork points.
+
 In an interactive terminal, suggestions are shown as the first input line is
 edited. For example, `/re` shows `/resume` and `/retry`; `/compact ` offers
 `history-reference` and `provider-native`; `/resume ` filters known session IDs;
@@ -833,9 +946,7 @@ Each changed view is persisted as `context.compacted` before the model request
 and is restored on resume, including a summary that is still above threshold.
 Programmatic callers select `autoCompactionMode`; an explicit
 `autoCompactionStrategies` array overrides it, and an empty array disables
-automatic compaction. The deprecated `providerNative: true` configuration and
-`providerNativeAutoCompaction: true` option now select native-only mode when no
-mode is specified; an explicit mode takes precedence.
+automatic compaction.
 
 ### History-reference work memory
 
@@ -872,8 +983,8 @@ so notes can be prepared for manual `/compact history-reference`. Only automatic
 history-reference mode exposes `new_context` and adds proactive guidance/warnings.
 Explicit custom strategy arrays keep their existing caller-defined behavior.
 
-The `read` tool runs without approval. `shell`, `edit`, and `write` require an
-allow-once, allow-for-session, or deny decision. The shell tool is not a sandbox.
+The `read`, `glob`, and `grep` tools run without approval. `shell`, `edit`, `write`,
+and `fetch` require an allow-once, allow-for-session, or deny decision.
 The read-only `session_history` tool also runs without approval and returns
 bounded pages of durable events from only the active session.
 Allow-for-session grants currently last for the running MaybeCode process and
@@ -907,7 +1018,7 @@ pnpm test:integration:maybecode
 
 The persistent permission integration check is opt-in. After `pnpm build`, set
 `MAYBECODE_PERSISTENT_RULES_LIVE=1` and optionally
-`MAYBECODE_PERSISTENT_RULES_MODEL=<configured-profile>`, then run
+`MAY_LIVE_MODEL=<configured-profile>`, then run
 `node --test apps/maybecode/test/integration/persistent-rules.test.mjs`.
 It uses the current user configuration and actual provider to write one isolated
 file twice, closing and reopening the Session between writes. It verifies one
@@ -924,7 +1035,7 @@ and `complete` preview data; `attach` and `use-prompt` explicitly submit user-le
 content; `watch`/`unwatch` manage notification-only subscriptions. See the bilingual
 [MCP guide](../../docs/en/guides/mcp.md).
 
-Both interactive terminal UIs support modern MCP form/URL elicitation, with
+The terminal UI supports modern MCP form/URL elicitation, with
 explicit review/send, decline/cancel, and manual URL navigation/resume. Answers
 are not command history. Library hosts must opt in with `mcpInteractions: true`
 and consume the controller interaction events; no UI means no advertised
@@ -940,7 +1051,7 @@ Session-bound controls; `task-attach` alone submits a completed result to a new
 Stopping local waiting is not remote cancellation. No automatic replay after
 restart. See the bilingual [Tasks guide](../../docs/en/guides/mcp-tasks.md).
 
-`/mcp apps` explicitly reports unsupported HTML in both terminal UIs. App-only
+`/mcp apps` explicitly reports unsupported HTML in the terminal UI. App-only
 tools are hidden even without a graphical Host; model-visible text fallback remains.
 Optional custom graphical integration: [Apps guide](../../docs/en/guides/mcp-apps.md).
 

package/README.zh-CN.md

@@ -0,0 +1,267 @@
+# MaybeCode
+
+[English](README.md)
+
+MaybeCode 是一个编程 Agent，可以读取项目、搜索文件和文本、修改代码、执行命令，
+以及访问网页文档。它提供 retained 终端界面、Web UI、会话恢复和团队委派。
+
+## 环境要求
+
+使用 **Node.js 22.16 或更新版本**。容器执行还需要 Docker Desktop 或兼容的
+Docker 运行时，并启动 Docker 服务。
+
+## 安装
+
+使用 npm 或 pnpm 全局安装公开发布的 package：
+
+```sh
+npm install --global @sortedyuan/maybecode
+pnpm add --global @sortedyuan/maybecode
+```
+
+## 配置模型
+
+在项目目录创建 `may.config.json`。在环境变量 `DEEPSEEK_API_KEY` 中配置
+provider API key。
+
+```json
+{
+  "providers": {
+    "deepseek": { "adapter": "deepseek-chat", "apiKeyEnv": "DEEPSEEK_API_KEY" }
+  },
+  "models": {
+    "deepseek": { "provider": "deepseek", "model": "deepseek-chat" }
+  },
+  "defaultModel": "deepseek"
+}
+```
+
+## 启动
+
+```sh
+maybecode --config may.config.json .
+maybecode --help
+```
+
+`--ui` 接受 `retained`（默认值）和 `web`。在终端执行 `/web`，可以打开与当前
+会话连接的浏览器界面。单独启动 Web UI 需要配置 `MAYBECODE_CONTROL_TOKEN`。
+
+## 恢复会话
+
+```sh
+maybecode --config may.config.json --continue .
+maybecode --config may.config.json --resume <session-id> .
+```
+
+普通启动会创建新会话。`--continue` 恢复工作目录最近的会话，`--resume` 选择指定
+会话，`/resume` 打开会话选择界面。保存的会话可以在重新启动后继续使用。
+
+## 权限模式
+
+默认模式自动批准 `read`、`glob` 和 `grep`。执行命令、修改文件、写入文件和
+`fetch` 网页请求需要审批。`fetch` 使用单独的网络权限类别，启用持久规则后也可以
+保存相应规则。
+
+`--yolo` 开启自动批准，`--no-yolo` 使用默认模式。明确的策略拒绝仍然有效。
+`/yolo on|off|status` 管理当前宿主的模式；修改模式前需要完成或取消正在执行的操作。
+模式变化应用于当前宿主的全部会话和界面，重新启动后使用启动配置。
+
+启用 `apps.maybecode.persistentRules` 后，项目的 `.may/permission-rules.json`
+保存持久规则。`/permissions list`、`revoke`、`allow` 和 `deny` 管理规则。
+文件编辑审批可以选择允许指定文件；规则使用项目、用户和 Agent 身份范围。
+详见[权限策略](../../docs/zh-CN/guides/permission-policy.md)。
+
+## 执行隔离
+
+`apps.maybecode.execution` 默认使用 `{ "mode": "host" }`，命令拥有当前用户的
+操作系统权限。容器模式需要提前拉取镜像，并配置相同的镜像名称：
+
+```sh
+docker pull nixery.dev/shell/git/ripgrep/util-linux
+```
+
+```json
+{
+  "apps": {
+    "maybecode": {
+      "execution": {
+        "mode": "container",
+        "image": "nixery.dev/shell/git/ripgrep/util-linux",
+        "network": "none",
+        "memoryBytes": 1073741824,
+        "cpuCount": 2
+      }
+    }
+  }
+}
+```
+
+镜像必须包含 `bash`、`git`、`rg` 和 `setsid`。容器使用非 root 用户、只读根目录、
+临时 `/tmp` 存储、禁用的网络，以及配置的内存和 CPU 限制。容器仅挂载工作目录。
+文件工具从宿主访问同一份文件。Shell、搜索工具、子 Agent 工具和已授权的团队检查
+使用配置的执行环境。MCP server 继续在宿主运行。Docker 服务不可用或镜像不存在时，
+应用启动失败。关闭应用时会等待执行资源终止。
+
+`fetch` 默认访问公网 HTTP/HTTPS origin。配置 `apps.maybecode.fetch.allowedOrigins`
+后，请求仅允许访问列表中的 origin，列表可以明确开放本地服务。`maxBytes`、
+`timeoutMs` 和 `maxRedirects` 限制响应。每个重定向目标都会重新检查。
+
+## 委派通知与模型更新
+
+自动请求和任务状态通知默认关闭。`/delegations notifications on|off|status` 管理
+当前进程的通知，`apps.maybecode.delegationNotifications: true` 在启动时开启通知。
+完整任务输出保存在持久记录中。
+
+`/model` 选择模型，`/effort` 选择 reasoning effort。更新要求应用空闲，并且没有
+正在运行的 Goal 或等待处理的 MCP 交互。更新保留会话历史、Goal、Skills、工作笔记
+和权限模式。程序宿主通过 `controller.application.updateModel()` 更新模型。
+模型插件保留模型选择的所有权。更新失败后需要成功重试才能继续提交输入。
+
+## 会话分支与项目版本
+
+项目默认使用 Git。已有仓库保留当前分支。首次批准修改项目的工具时，新项目会初始化
+仓库。修改请求在执行工具前保存文件状态，并在完成修改、检查和委派后保存检查点。
+失败或取消的请求保留未提交文件。Git 需要预先配置用户身份。
+
+`/fork` 根据完整回复创建会话分支，可以使用当前目录或新的 worktree。
+`/worktrees` 查看和管理工作目录。`/changes` 查看当前或指定请求、会话、commit
+的文件变化。恢复文件需要预览和确认。
+
+`apps.maybecode.git.autoCommit: false` 关闭自动提交，`readOnly: true` 限制项目
+修改，`git: false` 关闭项目 Git 管理。存储目录需要位于项目仓库之外。
+详见 [MaybeCode 指南](../../docs/zh-CN/guides/maybecode.md)。
+
+## Web UI
+
+`/web` 打开当前工作目录和会话的浏览器界面。终端和浏览器共享输出、审批、模型选择
+和会话变化。连接链接一次有效，刷新或断开后可以重新执行 `/web`。关闭浏览器页面
+保留运行中的任务；退出终端会关闭应用和 Web 服务。
+
+单独运行 `maybecode --ui web` 时，设置 `MAYBECODE_CONTROL_TOKEN` 为长度
+32 至 256 的可打印 ASCII 字符串。默认端口为 3940，可以通过 `--port` 修改。
+MCP 表单和 URL 交互提供预览、明确确认以及取消操作。
+详见 [Web UI 指南](../../docs/zh-CN/guides/web-ui.md)。
+
+## Plugin 组合与产品范围
+
+`openConfiguredMaybeCode({ plugins })` 接受自定义插件。Model、Context、Permission、
+Skills、Goals、History Memory、Delegation 和 Workspace Files 组成应用功能。
+MCP 和 tracing 由配置宿主管理，同一工作目录中的会话复用连接。关闭宿主会释放连接
+和 tracing processor。选定插件按照服务和 identifier 替换默认提供者，并验证依赖。
+
+MaybeCode 负责产品提示、工具装配、权限策略、修改预览、模型配置和界面命令。
+May 的通用组件负责执行、取消、审批、会话历史、Context 和资源生命周期。
+
+## 非交互团队
+
+`maybecode team run "Inspect this module" --workspace <path>` 默认启动两个只读
+worker 和一个 supervisor。`--preset supervisor|pipeline|parallel` 或 `--plan`
+选择角色、模型、工具权限和依赖。团队使用独立目录、共享额度和持久任务记录。
+
+执行状态与验收状态分别记录。配置的检查产生 `passed`、`failed` 或 `unverified`
+验收结果。`--mode coding` 开放明确列出的修改工具，`--allow-checks` 单独授权
+配置中的检查命令。检查继承 `apps.maybecode.execution`。`team diff` 导出补丁，
+`team apply --confirm <digest>` 在用户审阅后应用补丁。
+
+`team status`、`resume`、`cancel`、`retry` 和 `reconcile` 管理状态与恢复。
+详见[团队指南](../../docs/zh-CN/guides/maybecode-team.md)、
+[验收](../../docs/zh-CN/guides/maybecode-team-verification.md)、
+[编程任务](../../docs/zh-CN/guides/maybecode-team-coding.md)和
+[恢复](../../docs/zh-CN/guides/maybecode-team-recovery.md)。
+
+## 自定义界面与程序调用
+
+自定义界面通过 `MaybeCodeController` 提交操作，读取事件，并通过
+`controller.application` 访问当前会话的应用。切换会话后重新读取该字段。
+以下示例使用已经配置的模型；在支持 TypeScript 的运行环境中执行：
+
+```ts
+import { openConfiguredMaybeCode, type MaybeCodeController } from "@sortedyuan/maybecode";
+
+const controller: MaybeCodeController = await openConfiguredMaybeCode({
+  configPath: "may.config.json",
+});
+const observation = (async () => {
+  for await (const event of controller.events) {
+    console.log(event);
+  }
+})();
+
+try {
+  console.log(controller.application.modelInfo);
+  await (
+    await controller.submit({ input: "Inspect this workspace." })
+  ).result;
+} finally {
+  await controller.close();
+  await observation;
+}
+```
+
+控制器支持提交、steering、取消、审批、会话管理、历史以及 Context 管理。
+执行期间普通输入会取消当前操作并等待终止，然后开始新输入；`/steer` 在当前 Step
+完成后接收额外输入。`/stop` 取消当前操作和等待中的输入。
+
+retained 界面支持鼠标滚动、文本选择、剪贴板和终端 Markdown。`Ctrl+G` 后按 `D`
+切换工具详情，按 `T` 切换 reasoning 显示，按 `R` 定位当前请求的完整回复。
+`Tab` 切换到会话内容，方向键和 PageUp/PageDown 浏览内容。编辑区方向键管理输入
+历史，`Ctrl+J` 插入换行，`Enter` 提交。`MAY_TUI_LEADER` 和 `MAY_CLIPBOARD`
+配置快捷键与剪贴板行为。
+
+## 运行配置
+
+支持 `deepseek-chat`、`zhipu-chat`、`kimi-chat`、`anthropic-messages`、
+`openai-responses` 和 `openai-chat-completions` adapter。模型的
+`contextWindowTokens` 和 `maxOutputTokens` 提供 Context 预算信息。
+
+交互模式默认对暂时性模型请求错误最多尝试三次；`apps.maybecode.retry` 配置次数
+和等待时间，`false` 关闭重试。Team 模式分别计算每次 provider 请求。
+
+`apps.maybecode.observability` 配置不含内容的 JSONL tracing，默认关闭。
+文件名称包含本地日期，默认保留 60 天。关闭工作目录后刷新并关闭 processor。
+
+`apps.maybecode.mcpServers` 配置宿主 stdio 或 Streamable HTTP server。
+`/mcp` 查看连接与工具，`refresh` 更新目录，`reconnect` 重新连接。
+环境变量引用必须在启动时存在。OAuth 登录使用 `maybecode mcp login`。
+资源、prompt、采样和长期任务的权限与生命周期见
+[MCP 指南](../../docs/zh-CN/guides/mcp.md)。
+
+## 指令
+
+`apps.maybecode.instructionsDirectory` 指定包含非空 UTF-8 `system.md` 的目录，
+相对路径以配置文件目录为起点。它替换内置系统提示。
+项目规则从项目根目录到工作目录逐层读取，每层优先使用 `AGENTS.override.md`，
+其次使用 `AGENTS.md`。每个文件以及合计内容分别受 32 KiB 限制。
+应用打开、接受输入和每次 Run 前刷新项目规则。`/instructions` 查看有效内容。
+详见[指令组合](../../docs/zh-CN/guides/maybecode-instructions.md)。
+
+## 命令、Context 与存储
+
+`/new` 创建会话，`/resume` 管理历史会话，`/model` 和 `/effort` 管理模型，
+`/retry` 继续失败请求，`/status` 和 `/context` 查看状态，`/help` 查看命令。
+`/skills` 管理 Skills。`/goal start|status|pause|resume|cancel` 管理持久目标。
+`/recovery` 查看需要用户验证结果的中断工具记录。
+
+自动 Context 管理提供 `prune-summary`、`history-reference` 和 `provider-native`
+三种模式。历史引用模式使用持久工作笔记和历史检索，provider-native 要求模型支持。
+Context 变化写入会话记录，恢复会话时重新使用。`context_notes` 保存当前会话笔记，
+`get_context_remaining` 提供用量估计。详见
+[Context 管理](../../docs/zh-CN/guides/maybecode.md)。
+
+会话记录和目录默认保存在 `~/.may/maybecode`，内容为明文，每个会话需要单个活动
+写入者。文件修改提供有界 diff 预览，并记录版本化展示事件以支持会话恢复。
+
+## 测试
+
+```sh
+pnpm --filter @sortedyuan/maybecode test
+pnpm test:package:maybecode
+```
+
+打包检查安装完整依赖到独立消费者目录，编译两个 README 中的 TypeScript 示例，
+执行安装后的 `maybecode --help`，并验证 Web UI 启动。开发环境使用仓库声明的
+pnpm 版本。外部依赖优先使用缓存，并按需从 registry 下载。
+
+`pnpm test:integration:maybecode` 使用用户配置进行真实 DeepSeek 请求。
+持久权限集成测试需要明确启用 `MAYBECODE_PERSISTENT_RULES_LIVE=1`，使用实际
+provider 创建独立文件并验证规则复用。详情见 [English README](README.md#tests)。