docs: refine README product copy
This commit is contained in:
Tianyi Cui
@@ -1,6 +0,0 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# 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
|
||||
2026-07-22-product-first-root-readme.md: 3d295d39119e9dd70af53cef68948d928a69120a
|
||||
2026-07-22-product-first-root-readme.zh.md: ebfa0904536fe409873afa5dc88b76d4f7ee9dc7
|
||||
@@ -1,29 +0,0 @@
|
||||
# Agent Note: Product-first root README
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-07-22-product-first-root-readme.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The root README is the first page for people evaluating DeepSeek Harness, but SDK-first contributor detail competes with the shortest path from product identity to installation and launch. Exhaustive package inventories, architecture diagrams, demos, and duplicated technical explanations also age faster than the interfaces they describe.
|
||||
|
||||
## Decision
|
||||
|
||||
The root README presents DeepSeek Harness as an installable coding agent first. It names the SDK foundation, keeps the supported one-line installer, and puts the Web UI, TUI, and headless entry points before architecture and contributor material.
|
||||
|
||||
The capability overview stays compact: it identifies the familiar built-in coding capabilities, makes plugin extensibility the distinguishing design, and presents Code Mode and the self-referential Cordis tools as explicit opt-ins. Detailed contracts remain at their owning documentation and are linked instead of copied into the root README.
|
||||
|
||||
The English and Chinese READMEs share the product, installation, capability, development, and license structure. Their community sections intentionally follow the primary channel for each language audience: Twitter in English and the WeChat community QR code in Chinese. The QR code is the only retained README media because it is a functional entry point rather than product decoration.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Keep an SDK-first contributor README.** This makes the repository architecture visible immediately, but it delays the answer to what the product is and how to run it. Contributor orientation remains available through the development and architecture links.
|
||||
|
||||
**Adopt a full marketing page with badges, screenshots, an architecture diagram, a package catalog, and tutorials.** This provides more material on the landing page, but duplicates fast-moving facts and creates media maintenance work before the product surface is stable.
|
||||
|
||||
**Use the same community channel in both languages.** Exact channel symmetry is simpler, but it is less useful when the two language audiences gather in different places. The technical content remains paired while the community destination is audience-specific.
|
||||
|
||||
## Consequences
|
||||
|
||||
A new reader reaches a runnable interface quickly and can follow stable links for deeper SDK details. The root README stays small enough to update whenever the installer or CLI surface changes. Rich media, package inventories, and long-form tutorials remain outside this entry point until they have a durable owner and maintenance path.
|
||||
@@ -1,29 +0,0 @@
|
||||
# Agent Note: 以产品为先的根 README
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-07-22-product-first-root-readme.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
根 README 是评估 DeepSeek Harness 的读者最先看到的页面，但以 SDK 为先的贡献者信息会挤占从产品定位直达安装与启动的最短路径。详尽的包（package）清单、架构图、演示以及重复的技术说明，也比其描述的接口更快失效。
|
||||
|
||||
## 决策
|
||||
|
||||
根 README 首先将 DeepSeek Harness 呈现为一款可安装的 coding agent（编程智能体）。它说明产品基于 SDK，保留受支持的单行安装命令，并将 Web UI、TUI 和 Headless 入口置于架构与贡献者资料之前。
|
||||
|
||||
功能概览保持简洁：它说明常见的内置编程功能，突出插件扩展性这一差异化设计，并明确 Code Mode 和自指 Cordis 工具都需显式启用。详细契约留在各自的权威文档中；根 README 只提供链接，不复制内容。
|
||||
|
||||
中英文 README 采用相同的产品、安装、功能、开发和许可证结构。社区章节则有意采用各语言读者的主要渠道：英文版指向 Twitter，中文版提供微信社区二维码。二维码是 README 中唯一保留的媒体，因为它是实际入口，而非产品装饰。
|
||||
|
||||
## 备选方案
|
||||
|
||||
**保留以 SDK 为先的贡献者 README。** 这能让读者立即看到仓库架构，却延后了“产品是什么、如何运行”这两个答案。贡献者仍可通过开发与架构链接获得所需指引。
|
||||
|
||||
**采用包含徽章、截图、架构图、包清单和教程的完整营销页面。** 这会让落地页承载更多材料，却会重复易变事实，并在产品接口稳定前增加媒体维护工作。
|
||||
|
||||
**两种语言采用同一个社区渠道。** 渠道完全对称更简单，但当两种语言的读者聚集在不同平台时，这种做法实用性更低。技术内容保持配对，社区目的地则按读者群体选择。
|
||||
|
||||
## 影响
|
||||
|
||||
新读者可以快速进入可运行的界面，并通过稳定链接了解更深入的 SDK 细节。根 README 足够精简，可在安装器或 CLI 接口变化时及时更新。在富媒体、包清单和长篇教程拥有持久的负责方与维护路径之前，它们不进入这个产品入口。
|
||||
+2
-2
@@ -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: a32ad5cddd2bcaa9468031e5833aab8e78dac52b
|
||||
README.zh.md: 4ffb222b2f2bff8c41ac42c047ea034e4416d4d7
|
||||
README.md: 366bea0b6d68b7eca9f53581d3bb727574adb5ef
|
||||
README.zh.md: 0508b2c4a7a580f137315740135bf36154c6513b
|
||||
@@ -2,16 +2,18 @@
|
||||
|
||||
English | [中文](README.zh.md)
|
||||
|
||||
DeepSeek Harness (`dsh`) is an open-source coding agent built on the DeepSeek Harness SDK, where everything is a plugin.
|
||||
DeepSeek Harness (`dsh`) is an open-source coding agent built on the DeepSeek Harness SDK, where **everything is a plugin**.
|
||||
|
||||
## Install
|
||||
|
||||
Install `dsh` with one command. The installer requires `git` and Node `^22.19 || >=24`, offers to install `pnpm` when it is missing, and prompts for a DeepSeek API key:
|
||||
Install `dsh` with one command:
|
||||
|
||||
```sh
|
||||
curl -fsSL https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/master/scripts/install.sh | 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
|
||||
@@ -48,7 +50,7 @@ dsh -p "summarize this workspace"
|
||||
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 is 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).
|
||||
- **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
|
||||
@@ -62,7 +64,9 @@ pnpm install
|
||||
pnpm run test:coverage
|
||||
```
|
||||
|
||||
Start with the [development guide](docs/development.md), read the [architecture](docs/architecture.md) before changing packages, and follow [AGENTS.md](AGENTS.md) when working in this repository.
|
||||
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.
|
||||
|
||||
|
||||
+8
-4
@@ -2,16 +2,18 @@
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
DeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（编程智能体），一切皆插件。
|
||||
DeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（编程智能体），**一切皆插件**。
|
||||
|
||||
## 安装
|
||||
|
||||
使用一条命令安装 `dsh`。安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥：
|
||||
使用一条命令安装 `dsh`：
|
||||
|
||||
```sh
|
||||
curl -fsSL https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/master/scripts/install.sh | sh
|
||||
```
|
||||
|
||||
安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥。
|
||||
|
||||
安装器会将 DeepSeek Harness 克隆到 `~/.dsh/source`，把 `dsh` 链接到 `~/.local/bin`，然后启动它。再次运行该命令会更新源码目录。其他安装位置和选项见 [`scripts/install.sh`](scripts/install.sh)。
|
||||
|
||||
## 使用 DeepSeek Harness
|
||||
@@ -48,7 +50,7 @@ dsh -p "summarize this workspace"
|
||||
内置功能涵盖文件读取、编辑与搜索、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)。
|
||||
- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。
|
||||
- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/cordis/tool-cordis/README.md)。
|
||||
|
||||
## 社区
|
||||
@@ -66,7 +68,9 @@ pnpm install
|
||||
pnpm run test:coverage
|
||||
```
|
||||
|
||||
请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)；在本仓库工作时，请遵循 [AGENTS.md](AGENTS.md)。
|
||||
请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。
|
||||
|
||||
面向 agent：遵循 [AGENTS.md](AGENTS.md)。
|
||||
|
||||
DeepSeek Harness 目前处于预发布阶段。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user