docs: preserve established README voice

2026-07-30 16:47:27 +08:00
parent 254ead9871
commit 4d3e324467
7 changed files with 162 additions and 94 deletions
@@ -6,30 +6,28 @@ Status: implemented

 ## 问题

-根 README 是仓库的产品入口，但仅以产品视角描述 coding agent（编程智能体）会掩盖 SDK 与当前运行时的广度，而以 SDK 为先的包（package）清单则会把启动可运行 agent 的最短路径放到后面。如果把 README 当作通用营销文案，而非持续维护的产品契约，命令、能力声明和入口描述也会逐渐漂移。
+根 README 是仓库的产品入口。其产品优先的结构和既有语气仍然有效，但随着运行时不断扩展，具体入口和能力声明会逐渐陈旧。重写事实仍然正确的章节，会扩大评审范围，也会丢弃已经行之有效的措辞。

 ## 决策

-根 README 将 DeepSeek Harness 定义为以插件为原生构成单元的 coding agent 运行时，同时交付可组合的 SDK 与组装完成的 `dsh` agent。它将使命定位与已交付事实分开，并首先给出受支持的单行安装命令。
+只要背后的事实仍然正确，根 README 就保留既有结构、顺序和措辞。刷新时只修正陈旧声明，并补充呈现已交付内容所需的信息；不会因为仓库规模增长就重构整篇叙事。

-安装命令之前的一则说明感谢早期用户，坦率说明内测版本仍未完成、整体完成度还很低，距离团队希望交付的体验还有差距，并邀请用户直接反馈故障、困惑和所有不顺手之处。它明确这些不足是产品的问题，而非用户的问题；紧接其后的预发布提醒则清楚说明兼容性边界。
+安装说明之前的一则文字感谢内测用户，说明功能和体验仍待完善，并邀请大家通过企业微信群直接反馈失败、困惑和不顺手之处。技术性的预发布声明仍保留在原有的开发章节位置。

-README 列出 TUI、Web、Headless、ACP（Agent Client Protocol）以及 Python/JSON-RPC 入口，并为每个入口提供命令或归属文档链接。它按编码、编排和运维三个类别概述能力，同时说明每种组合都自行选择插件。包与服务的完整清单仍由生成图和包分组文档维护。
+用户入口章节在已有的 Web、TUI 和 Headless 入口旁补充 ACP（Agent Client Protocol）自动化服务器和 Python/JSON-RPC SDK。能力段落沿用简洁清单的写法，补充已经交付的 PTY、LSP、Web、目标、规划、任务、沙箱、审批、会话查询和遥测等能力类别，并说明不同组合只选用其中一部分。相邻的一条列表项说明权威会话日志规则，因为持久化、回放、查询、遥测和各类接口都依赖它。

-以插件为原生构成单元是 README 的组织原则，而非一句口号：README 通过 `cordis.yml` 将可替换服务、类型化事件与组合方式关联起来，并明确面向模型的行为、持久化、回放、查询、遥测和 UI 投影都以权威会话日志为基础。详细契约仍由架构文档、CLI（命令行界面）、示例、实操手册（cookbook）和生成目录各自维护。
-
-中英文 README 采用相同的技术结构。两侧的社区章节分别指向各自语言受众的主要交流渠道。文档网站继续使用独立的用户指南首页；仓库 README 不加入该投影。
+包（package）与服务的完整清单仍由各自的归属文档维护。中英文 README 采用相同的技术结构，但社区章节仍分别指向各自语言受众的主要交流渠道。文档网站继续使用独立的用户指南首页。

 ## 考虑过的替代方案

-**只展示组装完成的 coding agent。** 这样能给出最简短的产品介绍，但会让 SDK、其他入口和可替换的运行时 seam 显得无足轻重，尽管它们都是仓库中已经交付的组成部分。
+**围绕新的产品叙事重写 README。** 完整重写能够突出所有现有入口和能力，但也会替换准确且已经过评审的文案，造成不必要的变动。现有事实能够纳入既有的产品优先结构。

 **将仓库呈现为 SDK 和包清单。** 这样能立即展现实现广度，却会迫使新读者从包名反推出产品。包索引与生成的能力图仍是权威清单。

 **使用包含截图、徽章和重复教程的长篇营销页面。** 富媒体能够展示稳定的产品使用路径，但其内容会独立于命令和源码契约而逐渐陈旧。根 README 保持紧凑，并链接到可运行示例和各自维护的指南。

-**将根 README 投影为文档网站首页。** 使用同一个首页可以避免两套叙事，但文档网站的用户指南与仓库面向开发者和产品的入口在导航和维护需求上并不相同。两者继续作为独立来源，并链接到相同的架构文档和指南。
+**将根 README 投影为文档网站首页。** 使用同一个首页可以避免两套叙事，但文档网站的用户指南与仓库面向产品和开发者的入口在导航和维护需求上并不相同。

 ## 结果

-新读者可以在了解包拓扑之前完成安装或选择运行时入口，SDK 读者也能理解扩展模型，而无需把生成目录复制进正文。任何受影响的命令、入口、预发布边界或高层能力类别发生变化时，README 都必须同步更新；每项声明都可以依据源码或归属文档进行评审核验。
+评审者可以区分事实更新与编辑性重写；今后的更新会保留既有措辞，除非其含义已经不再正确或完整。受影响的命令、入口、预发布边界或高层能力类别发生变化时，README 仍须同步更新；完整细节则继续以链接方式提供，而不是复制到正文。