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 接口变化时及时更新。在富媒体、包清单和长篇教程拥有持久的负责方与维护路径之前，它们不进入这个产品入口。
|
||||
Reference in New Issue
Block a user