Product-first root README
产品优先的根 README
The root README is the repository's product entry point. Its product-first structure and established voice remain useful, but concrete entry points and capability claims drift as the runtime grows. Rewriting sections whose facts remain correct increases the review surface and discards language that already works.
English
Problem
The root README is the repository's product entry point. Its product-first structure and established voice remain useful, but concrete entry points and capability claims drift as the runtime grows. Rewriting sections whose facts remain correct increases the review surface and discards language that already works.
Decision
The root README is a compact product and contributor entry point. It states the product identity and plugin architecture, links the documentation site, marks the developer-preview and safety status, and then gives the supported npm and source launch paths.
Both launch paths start the Web UI through the dsh profile entry point. The source path builds the checkout before it runs pnpm dsh web. Detailed ACP, TUI, SDK, capability, and package guidance stays in the user guide, architecture documentation, and package map instead of being repeated on the landing page.
The remaining sections link community support, contribution guidance, development documentation, agent instructions, the license, and third-party notices. The English and Chinese README sides keep the same technical structure while their community links serve their language audiences. The documentation website keeps a separate quick-start entry route.
Alternatives considered
Rewrite the README around a new product narrative. A complete rewrite can make every current surface prominent, but it replaces accurate, reviewed copy and creates unnecessary churn. Current facts fit the established product-first structure.
Present the repository as an SDK and package catalog. This exposes implementation breadth immediately but makes a new reader reconstruct the product from package names. The package map and generated capability graph remain the authoritative inventories.
Use a long marketing page with screenshots, badges, and duplicated tutorials. Rich media can demonstrate a stable product journey, but it ages separately from commands and source contracts. The root stays compact and links to runnable examples and owned guides.
Project the root README as the documentation website home page. A single landing page avoids two narratives, but the website's user guide and the repository's product/developer entry point have different navigation and maintenance needs. The documentation root sends readers to quick start instead.
Consequences
Reviewers can distinguish factual refreshes from editorial rewrites, and future updates retain established wording unless its meaning becomes false or incomplete. The README must still change with affected commands, entry points, release-stage claims, or high-level capability families, while exhaustive detail remains linked rather than copied.
中文
问题
根 README 是仓库的产品入口。其产品优先的结构和既有语气仍然有效，但随着运行时不断扩展，具体入口和能力声明会逐渐陈旧。重写事实仍然正确的章节，会扩大评审范围，也会丢弃已经行之有效的措辞。
决策
根 README 是简短的产品和贡献者入口。它说明产品定位与插件架构，链接文档站，标明开发者预览与安全状态，然后给出受支持的 npm 和源码启动路径。
两条启动路径都通过 dsh profile 入口启动 Web UI。源码路径先构建当前检出，再运行 pnpm dsh web。ACP、TUI、SDK、能力和包的详细说明由用户指南、架构文档与包索引维护，不在入口页重复。
其余章节链接社区支持、贡献指南、开发文档、agent 指令、许可证与第三方声明。中英文 README 保持相同技术结构，社区链接分别服务各自语言受众。文档网站保留独立的快速开始入口路由。
考虑过的替代方案
围绕新的产品叙事重写 README。 完整重写能够突出所有现有入口和能力，但也会替换准确且已经过评审的文案，造成不必要的变动。现有事实能够纳入既有的产品优先结构。
将仓库呈现为 SDK 和包清单。 这样能立即展现实现广度，却会迫使新读者从包名反推出产品。包索引与生成的能力图仍是权威清单。
使用包含截图、徽章和重复教程的长篇营销页面。 富媒体能够展示稳定的产品使用路径，但其内容会独立于命令和源码约定而逐渐陈旧。根 README 保持紧凑，并链接到可运行示例和各自维护的指南。
将根 README 投影为文档网站首页。 使用同一个首页可以避免两套叙事，但文档网站的用户指南与仓库面向产品和开发者的入口在导航和维护需求上并不相同。文档根路由则将读者引导至快速开始。
结果
评审者可以区分事实更新与编辑性重写；今后的更新会保留既有措辞，除非其含义已经不再正确或完整。受影响的命令、入口、发布阶段声明或高层能力类别发生变化时，README 仍须同步更新；完整细节则继续以链接方式提供，而不是复制到正文。