Merge remote-tracking branch 'origin/master' into worktree/comprehensive-pre-push

README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-README.md: 8b34d6177834e1c410b2c3ecaf32154de42520b4
-README.zh.md: cf029cc0bb8c5aa527d14753803eac4c28ab9de7
+README.md: 27774fd3e0ffc821e7287f6153906a5d21530dc2
+README.zh.md: b7d08f2bc948d0a6d388dd672c5a702bc7da6f6f

README.md

@@ -2,32 +2,76 @@
 
 English | [中文](README.zh.md)
 
-The **DeepSeek Harness SDK** is a plugin-based SDK for building agent harnesses.
+DeepSeek Harness (`dsh`) is an open-source coding agent built on the DeepSeek Harness SDK.
+
+It uses an architecture where **everything is a plugin**.
 
 ## Install
 
-Install the `dsh` coding agent with one line — it needs `git` and Node `^22.19 || >=24`, and offers to install `pnpm` if it is missing:
+Install `dsh` with one command:
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/master/scripts/install.sh | sh
 ```
 
-It clones the harness to `~/.dsh/source`, runs `pnpm install`, symlinks `dsh` into `~/.local/bin` (offering to add it to your PATH), prompts once for your `DEEPSEEK_API_KEY`, and launches `dsh`; re-running it updates an existing checkout. Run from inside a checkout (`sh scripts/install.sh`) it reuses that checkout and skips the clone. The overridable `DSH_*` variables are documented in [`scripts/install.sh`](scripts/install.sh).
+The installer requires `git` and Node `^22.19 || >=24`, offers to install `pnpm` when it is missing, and prompts for a DeepSeek API key.
+
+The installer clones DeepSeek Harness to `~/.dsh/source`, links `dsh` into `~/.local/bin`, and launches it. Re-running the command updates the checkout. See [`scripts/install.sh`](scripts/install.sh) for alternate install locations and other options.
+
+## Use DeepSeek Harness
+
+### Web UI
+
+For the recommended local interface, build the frontend after installation and after each update, then start the Web UI:
+
+```sh
+pnpm --dir ~/.dsh/source run build:web
+dsh web
+```
+
+The Web UI is served at `http://127.0.0.1:3080` by default.
+
+### TUI
+
+Start the full-screen terminal interface:
+
+```sh
+dsh
+```
+
+### Headless
+
+Run one task, print the final answer, and exit:
+
+```sh
+dsh -p "summarize this workspace"
+```
+
+## Why DeepSeek Harness
+
+Built-in capabilities cover file reading, editing, and search; shell execution; reusable skills; task tracking; subagents and workflows; persistent sessions; and context compaction. The TUI also includes Plan Mode.
+
+- **Everything is a plugin.** Models, tools, policies, storage, context management, and interfaces are composable [Cordis plugins](docs/user/develop/basic/index.md), so deployments can extend or replace behavior without forking the agent loop. See the [architecture](docs/architecture.md) for the underlying design.
+- **Code Mode (opt-in).** It exposes a `run_code` tool and a generated TypeScript SDK; only program output re-enters model context. See [Code Mode](packages/core/tools/README.md#code-mode).
+- **Self-referential Cordis tools are opt-in.** They let the agent inspect its live runtime and mount or unmount plugins while it runs. See the [Cordis tools](packages/cordis/tool-cordis/README.md).
+
+## Community
+
+Follow <a href="https://x.com/Deepseekharness">DeepSeek Harness on Twitter</a> for project updates.
 
 ## Development
 
-This monorepo is built on the [Cordis](https://github.com/cordiverse/cordis) framework (vendored as source under `vendor/`), microkernel-style: everything is a plugin.
-
 ```sh
 pnpm install
-pnpm run test          # vitest
-# Agent demos require DEEPSEEK_API_KEY.
-pnpm run demo:tui      # full-screen TUI coding agent
-pnpm run demo:headless "task" # one-shot coding agent
-pnpm run demo:cordis   # self-referential agent demo
-pnpm run demo:acp      # ACP server agent demo
+pnpm run test:coverage
 ```
 
-For humans, start with the [development guide](docs/development.md) for local setup, hooks, environment variables, and quality gates, then read the [architecture design](docs/architecture.md) and [documentation graph index](docs/graph-atlas.md) before package work. Local context lives in [packages/](packages/) and [vendor/](vendor/).
+Start with the [development guide](docs/development.md) and read the [architecture](docs/architecture.md) before changing packages.
 
 For agents, follow [AGENTS.md](AGENTS.md).
+
+DeepSeek Harness is currently pre-release.
+
+## License
+
+[BSD 3-Clause](LICENSE)

README.zh.md

@@ -2,32 +2,80 @@
 
 [English](README.md) | 中文
 
-**DeepSeek Harness SDK** 是用于构建 agent harness（智能体框架）的 SDK，采取基于插件的设计。
+DeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（编程智能体）。
+
+它采用了**一切皆插件**的架构。
 
 ## 安装
 
-一行命令即可安装 `dsh` 编码智能体——需要 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时会询问是否代为安装：
+使用一条命令安装 `dsh`：
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/master/scripts/install.sh | sh
 ```
 
-脚本会把 harness 克隆到 `~/.dsh/source`，运行 `pnpm install`，把 `dsh` 软链接到 `~/.local/bin`（并询问是否加入 PATH），提示输入一次 `DEEPSEEK_API_KEY`，随后启动 `dsh`；再次运行会更新已有的检出。若在检出目录内运行（`sh scripts/install.sh`），脚本会复用当前检出并跳过克隆。可覆盖的 `DSH_*` 变量见 [`scripts/install.sh`](scripts/install.sh)。
+安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥。
+
+安装器会将 DeepSeek Harness 克隆到 `~/.dsh/source`，把 `dsh` 链接到 `~/.local/bin`，然后启动它。再次运行该命令会更新源码目录。其他安装位置和选项见 [`scripts/install.sh`](scripts/install.sh)。
+
+## 使用 DeepSeek Harness
+
+### Web UI
+
+推荐在本地使用 Web UI。安装完成后以及每次更新后，请先构建前端，再启动 Web UI：
+
+```sh
+pnpm --dir ~/.dsh/source run build:web
+dsh web
+```
+
+Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。
+
+### TUI
+
+启动全屏终端界面：
+
+```sh
+dsh
+```
+
+### Headless
+
+运行一项任务，打印最终答案后退出：
+
+```sh
+dsh -p "summarize this workspace"
+```
+
+## 为什么选择 DeepSeek Harness
+
+内置功能涵盖文件读取、编辑与搜索、shell 执行、可复用 skill（技能）、任务跟踪、subagent 与工作流、持久化会话，以及上下文压缩（context compaction）。TUI 还包含 Plan Mode。
+
+- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均可组合为 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。
+- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。
+- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/cordis/tool-cordis/README.md)。
+
+## 社区
+
+扫描二维码，或打开 <a href="https://wj.qq.com/s2/27234598/03eb/">DeepSeek Harness 微信社区申请页面</a> 申请加入。
+
+<p>
+  <img src="assets/community-wecom-survey.png" alt="DeepSeek Harness 微信社区二维码" width="240">
+</p>
 
 ## 开发
 
-本 monorepo 基于 [Cordis](https://github.com/cordiverse/cordis) 框架构建（以源码形式收录在 `vendor/` 下），采用微内核风格：所有功能都以插件形式提供。
-
 ```sh
 pnpm install
-pnpm run test          # vitest
-# Agent demos require DEEPSEEK_API_KEY.
-pnpm run demo:tui      # full-screen TUI coding agent
-pnpm run demo:headless "task" # one-shot coding agent
-pnpm run demo:cordis   # self-referential agent demo
-pnpm run demo:acp      # ACP server agent demo
+pnpm run test:coverage
 ```
 
-面向开发者：先读[开发指南](docs/development.md)，了解本地环境搭建、钩子、环境变量与质量门禁，动手改 package 之前再读[架构设计](docs/architecture.md)和[文档关系图索引](docs/graph-atlas.md)。局部上下文见 [packages/](packages/) 与 [vendor/](vendor/)。
+请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。
 
 面向 agent：遵循 [AGENTS.md](AGENTS.md)。
+
+DeepSeek Harness 目前处于预发布阶段。
+
+## 许可证
+
+[BSD 3-Clause](LICENSE)