docs: make the top-level README product-first

2026-07-23 00:15:44 +08:00
parent 30a1ea7cec
commit ef325b02fa
14 changed files with 172 additions and 635 deletions
@@ -0,0 +1,6 @@
 # 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
@@ -0,0 +1,29 @@
 # 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.
@@ -0,0 +1,29 @@
 # 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 接口变化时及时更新。在富媒体、包清单和长篇教程拥有持久的负责方与维护路径之前，它们不进入这个产品入口。
@@ -1,158 +0,0 @@
 ---
 name: dsh-arch-diagram
 description: Regenerate the DeepSeek Harness "System overview" architecture PNGs (English + Chinese) that the top-level README embeds. Reflects the current state of packages/* and docs/architecture.md. Use when the codebase adds/removes/renames services and the README diagram must be refreshed.
 ---
 # dsh-arch-diagram
 Produces `assets/arch-en.png` and `assets/arch-zh.png` in this repo — the two hero images embedded at the top of `README.md` and `README.zh.md`.
 The pipeline is HTML + Chrome headless, so text quality, layout, and connector geometry are **deterministic** — every rerun produces the same output regardless of model.
 Aesthetic is locked to the DeepSeek brand: light blue gradient background, brand-blue Cordis bar, sans-serif everywhere, no serif / no italic / no hand-drawn feel.
 ---
 ## When to use
 - User asks to "regenerate" or "refresh" the Harness architecture diagram
 - User points out `packages/` has changed (new services, renames) and the README diagram is stale
 - User just added a new `packages/<family>/` or a new `ctx.*` service and wants the diagram to reflect it
 ## When NOT to use
 - User wants a different diagram (Code Mode, Workflow fanout, agent lifecycle) — those belong in `docs/` and need their own skill
 - User wants a different visual aesthetic (dark mode, hand-drawn, editorial-serif) — this skill is locked to DeepSeek brand
 ---
 ## Workflow
 ### 1. Enumerate current services from the repo
 The diagram is grounded in two lists that live in the docs:
 - **Default Services** — from `packages/core/*` and `docs/architecture.md`'s "Default Services" table. As of last refresh: `ctx.sessions`, `ctx.systemPrompt`, `ctx.tools`, `ctx.agents`, `ctx.agentLoop`.
 - **Capability Services** — from the non-core capability packages and `docs/architecture.md`'s "Capability Services" table. As of last refresh: `ctx.llm`, `ctx.bash`, `ctx.sandbox`, `ctx.codeRuntime`, `ctx.fs`, `ctx.skills`, `ctx.web`, `ctx.compact`, `ctx.subagents`, `ctx.workflows`, `ctx.sessionPersistence`, `ctx.sessionQuery`.
 **Do this**:
 1. Read `docs/architecture.md`
 2. Extract the two `ctx.*` tables verbatim
 3. Cross-check against `packages/`: services live under `packages/core/*` (defaults) or under `packages/<family>/<package>/` (capabilities). The inner package dir mirrors the npm name without the `@deepseek-ai/dsh-` prefix — e.g. `packages/session-query/session-query/` publishes `@deepseek-ai/dsh-session-query`. Never assume the inner dir carries a `dsh-` prefix.
 ### 2. Diff against the current HTML templates
 Read `harness-arch-en.html` and `harness-arch-zh.html` in this skill directory. Pull out the currently-rendered `ctx.*` names. Report the diff:
 ```
 Default services: no change
 Capability services: + ctx.<new>, − ctx.<removed>, ↻ ctx.<renamed>
 ```
 ### 3. Update the templates
 If there are changes, edit both HTML files in place. Each card is one line:
 ```html
 <div class="card"><span class="name">ctx.something</span><span class="desc">short description</span></div>
 ```
 For a **new** service:
 - Description is **short** — 2–4 words (EN), 3–6 chars (ZH)
 - Ground the description in what the package's README or its `ctx.<name>.register()` **actually** does. Do NOT paraphrase from an abstract or invent capabilities the code doesn't have.
 - Add the card in **both** languages, in docs order.
 For a **removed** service: delete the card in both files.
 For a **renamed** service: update the `.name` span in both files.
 **Do not touch the layout**. Rows are:
 - Top row (`row top`): exactly 5 default-service cards
 - Bottom row (`row bottom`): 12 capability-service cards
 If the capability count grows past ~13, the row gets visually tight. Stop and ask the user before shrinking fonts or wrapping to two rows.
 ### 4. Render to PNG
 ```bash
 bash .agents/skills/dsh-arch-diagram/render.sh
 ```
 Default output: `<repo>/assets/arch-en.png` and `<repo>/assets/arch-zh.png` — the paths that `README.md` and `README.zh.md` already reference.
 Pass an alternate directory as `$1` to write elsewhere. `CHROME` and `PORT` env vars override the browser path and http.server port.
 The script:
 - Spins up a temporary `python3 -m http.server` on `127.0.0.1` (needed so Google Fonts CDN loads reliably in Chrome headless)
 - Runs Chrome headless twice at `--force-device-scale-factor=2 --window-size=1536,580`
 - Writes two 3072×1160 PNGs (~600 KB each)
 - Tears down the server
 ### 5. Verify by eye — mandatory, do not skip
 After rendering, **open each PNG and visually check every item** in this list. Do not report the diagram as done without going through it.
 - [ ] Top-row card count matches the Default Services list you extracted in §1, every name rendered in full (no truncation on the longest, e.g. `ctx.systemPrompt` / `ctx.agentLoop`)
 - [ ] Bottom-row card count matches the Capability Services list you extracted in §1, every name in full (especially the longest, e.g. `ctx.sessionPersistence`)
 - [ ] Every card has a description underneath, and the description matches what the code does (not made up)
 - [ ] Bar reads `Cordis · microkernel (vendored)` (EN) / `Cordis · 微内核 (vendored)` (ZH)
 - [ ] Number of vertical connector lines equals (top-row cards + bottom-row cards) from §1. All straight vertical, all parallel, each reaching the horizontal center of its card
 - [ ] `cordis.yml` sidebar visible on the right; dashed arrow points left into the bar
 - [ ] `deployment leaf` / `部署清单` and `picks which plugins load` / `决定哪些插件加载` are readable and NOT crossed through by any connector line
 - [ ] Chinese descriptions render as CJK glyphs, not `□` tofu boxes (means fonts loaded)
 - [ ] No large empty gradient area at the bottom of the image — if there is, tune `--window-size` in `render.sh`
 If any check fails: fix the CSS or template, re-run `render.sh`, re-check. Do not report "done" on first render without visually confirming.
 ---
 ## Design system (locked — do not modify without explicit user request)
 Colors:
 - Background: `linear-gradient(135deg, #ffffff 0%, #e8effc 100%)`
 - Brand blue (Cordis bar + connectors): `#4a6ef5`
 - Ink text: `#1a1a1a`
 - Muted text: `#8a8f9c`
 - Card border: `#dde3ef`
 - Card fill: `#ffffff`
 Typography (**sans-serif only** — never serif, never italic):
 - English title & body: **Inter** (Google Fonts)
 - Chinese title & body: **Noto Sans SC** (Google Fonts) with `PingFang SC` local fallback
 - Code labels (`ctx.*`, `cordis.yml`, `vendored`): **JetBrains Mono** (Google Fonts)
 Layout:
 - `.page` max-width 1560 px, centered
 - `.bus-row`, `.row.top`, `.row.bottom` all 96% width, centered
 - Top row: `flex: 1` on each card (equal widths)
 - Bottom row: `justify-content: space-between` + `flex: 0 0 auto` on each card — cards keep their intrinsic (nowrap) width and adjacent card backgrounds cannot clip a description
 - Bus: `#4a6ef5` filled, 60 px tall, 8 px radius
 - `cordis.yml` sidebar `position: absolute` at `left: calc(100% + 20px)` of `.bus-row`, width 130 px
 - All connectors: CSS `::before` / `::after` pseudo-elements, 2 px wide, 40 px tall, `#4a6ef5`, centered via `left: 50%; transform: translateX(-50%)` — this is what guarantees pixel-perfect vertical parallel lines regardless of card content
 Rendering:
 - Chrome headless `--force-device-scale-factor=2`
 - `--window-size=1820,580` → output is 3640×1160 (aspect ~3.14:1, wider than square-ish so a 12-card capability row fits without truncation)
 - Local http.server on `127.0.0.1` so CDN fonts load cleanly
 ---
 ## Files in this skill
 - `SKILL.md` — this file
 - `harness-arch.css` — shared design system (colors, fonts, layout, connectors)
 - `harness-arch-en.html` — English template
 - `harness-arch-zh.html` — Chinese template
 - `render.sh` — Chrome headless renderer
 Templates are self-contained. Fonts load from Google Fonts CDN; no local font files.
 ---
 ## Rules I keep breaking (and shouldn't)
 1. **Verify the output by looking at it.** Don't report "done" and move on — actually inspect each PNG and check every item in §5.
 2. **Ground service descriptions in the code, not the docs' abstract, not the marketing copy.** If unsure what a package does, read its `src/` or the `ctx.<name>.register()` block.
 3. **Don't touch layout unless asked.** 96% row/bar width, 40 px connector height, and 60 px bar height are all tuned. Card counts grow one at a time; once the bottom row starts to visibly overflow again (adjacent card backgrounds clipping a description, or the `cordis.yml` sidebar falling outside the render viewport), stop and ask before shrinking fonts, widening the viewport further, or wrapping to two rows.
 4. **Never introduce a serif font or italic.** Not for titles, not for annotations, not "to make it feel editorial." This diagram is DeepSeek brand: sans-serif, upright, only.
@@ -1,66 +0,0 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=1536, initial-scale=1.0">
  <title>DeepSeek Harness · Architecture</title>
  <link rel="stylesheet" href="harness-arch.css">
 </head>
 <body>
  <div class="page">
    <p class="eyebrow">ARCHITECTURE</p>
    <h1>System overview</h1>
    <div class="diagram">
      <p class="section-label top">DEFAULT SERVICES</p>
      <div class="row top">
        <div class="card"><span class="name">ctx.sessions</span><span class="desc">event-sourced log</span></div>
        <div class="card"><span class="name">ctx.systemPrompt</span><span class="desc">prompt assembly</span></div>
        <div class="card"><span class="name">ctx.tools</span><span class="desc">tool registry &amp; pipeline</span></div>
        <div class="card"><span class="name">ctx.agents</span><span class="desc">agent handles &amp; events</span></div>
        <div class="card"><span class="name">ctx.agentLoop</span><span class="desc">ReAct control loop</span></div>
      </div>
      <div class="bus-row">
        <div class="bus">
          <span class="core">Cordis</span>
          <span class="dot">·</span>
          <span class="core">microkernel</span>
          <span class="vendored">(vendored)</span>
        </div>
        <div class="yml-side">
          <div class="yml-arrow">
            <svg viewBox="0 0 30 12" width="30" height="12" xmlns="http://www.w3.org/2000/svg">
              <line x1="30" y1="6" x2="8" y2="6" stroke="#8a8f9c" stroke-width="1.2" stroke-dasharray="3 3"/>
              <polyline points="8,3 2,6 8,9" fill="none" stroke="#8a8f9c" stroke-width="1.2" stroke-linejoin="round" stroke-linecap="round"/>
            </svg>
          </div>
          <div class="yml-box">
            <div class="file">cordis.yml</div>
            <div class="sub">deployment leaf</div>
          </div>
          <div class="yml-note">picks which plugins load</div>
        </div>
      </div>
      <div class="row bottom">
        <div class="card"><span class="name">ctx.llm</span><span class="desc">LLM provider adapter</span></div>
        <div class="card"><span class="name">ctx.bash</span><span class="desc">shell execution</span></div>
        <div class="card"><span class="name">ctx.sandbox</span><span class="desc">process confinement</span></div>
        <div class="card"><span class="name">ctx.codeRuntime</span><span class="desc">JS worker runtime</span></div>
        <div class="card"><span class="name">ctx.fs</span><span class="desc">filesystem + policy</span></div>
        <div class="card"><span class="name">ctx.skills</span><span class="desc">reusable skills</span></div>
        <div class="card"><span class="name">ctx.web</span><span class="desc">search &amp; fetch</span></div>
        <div class="card"><span class="name">ctx.compact</span><span class="desc">context compression</span></div>
        <div class="card"><span class="name">ctx.subagents</span><span class="desc">spawn / fork / ACP</span></div>
        <div class="card"><span class="name">ctx.workflows</span><span class="desc">dynamic orchestration</span></div>
        <div class="card"><span class="name">ctx.sessionPersistence</span><span class="desc">JSONL / SQLite</span></div>
        <div class="card"><span class="name">ctx.sessionQuery</span><span class="desc">unified log reads</span></div>
      </div>
      <p class="section-label bottom">CAPABILITY SERVICES</p>
    </div>
  </div>
 </body>
 </html>
@@ -1,66 +0,0 @@
 <!DOCTYPE html>
 <html lang="zh-CN">
 <head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=1536, initial-scale=1.0">
  <title>DeepSeek Harness · 架构</title>
  <link rel="stylesheet" href="harness-arch.css">
 </head>
 <body>
  <div class="page">
    <p class="eyebrow cn">架 构</p>
    <h1 class="cn">系统一览</h1>
    <div class="diagram">
      <p class="section-label top cn">默 认 服 务</p>
      <div class="row top">
        <div class="card"><span class="name">ctx.sessions</span><span class="desc cn">事件溯源日志</span></div>
        <div class="card"><span class="name">ctx.systemPrompt</span><span class="desc cn">系统提示词组装</span></div>
        <div class="card"><span class="name">ctx.tools</span><span class="desc cn">工具注册与执行</span></div>
        <div class="card"><span class="name">ctx.agents</span><span class="desc cn">Agent 实例与事件</span></div>
        <div class="card"><span class="name">ctx.agentLoop</span><span class="desc cn">ReAct 控制循环</span></div>
      </div>
      <div class="bus-row">
        <div class="bus cn">
          <span class="core">Cordis</span>
          <span class="dot">·</span>
          <span class="core">微内核</span>
          <span class="vendored">(vendored)</span>
        </div>
        <div class="yml-side">
          <div class="yml-arrow">
            <svg viewBox="0 0 30 12" width="30" height="12" xmlns="http://www.w3.org/2000/svg">
              <line x1="30" y1="6" x2="8" y2="6" stroke="#8a8f9c" stroke-width="1.2" stroke-dasharray="3 3"/>
              <polyline points="8,3 2,6 8,9" fill="none" stroke="#8a8f9c" stroke-width="1.2" stroke-linejoin="round" stroke-linecap="round"/>
            </svg>
          </div>
          <div class="yml-box">
            <div class="file">cordis.yml</div>
            <div class="sub cn">部署清单</div>
          </div>
          <div class="yml-note cn">决定哪些插件加载</div>
        </div>
      </div>
      <div class="row bottom">
        <div class="card"><span class="name">ctx.llm</span><span class="desc cn">模型适配层</span></div>
        <div class="card"><span class="name">ctx.bash</span><span class="desc cn">命令行执行</span></div>
        <div class="card"><span class="name">ctx.sandbox</span><span class="desc cn">进程隔离</span></div>
        <div class="card"><span class="name">ctx.codeRuntime</span><span class="desc cn">JS 运行时</span></div>
        <div class="card"><span class="name">ctx.fs</span><span class="desc cn">文件读写</span></div>
        <div class="card"><span class="name">ctx.skills</span><span class="desc cn">可复用技能</span></div>
        <div class="card"><span class="name">ctx.web</span><span class="desc cn">网页搜索抓取</span></div>
        <div class="card"><span class="name">ctx.compact</span><span class="desc cn">上下文压缩</span></div>
        <div class="card"><span class="name">ctx.subagents</span><span class="desc cn">子智能体</span></div>
        <div class="card"><span class="name">ctx.workflows</span><span class="desc cn">动态编排</span></div>
        <div class="card"><span class="name">ctx.sessionPersistence</span><span class="desc cn">会话持久化</span></div>
        <div class="card"><span class="name">ctx.sessionQuery</span><span class="desc cn">会话日志查询</span></div>
      </div>
      <p class="section-label bottom cn">能 力 服 务</p>
    </div>
  </div>
 </body>
 </html>
@@ -1,220 +0,0 @@
 /* DeepSeek brand — bone-white + brand-blue, all sans-serif, no italic, no serif. */
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Noto+Sans+SC:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap');
 :root {
  --bg-top:      #ffffff;
  --bg-bot:      #e8effc;
  --ink:         #1a1a1a;
  --muted:       #8a8f9c;
  --card-bd:     #dde3ef;
  --card-bg:     #ffffff;
  --brand:       #4a6ef5;
  --brand-soft:  #dbe4fe;
  --sans:  'Inter', 'Noto Sans SC', 'PingFang SC', -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
  --cn:    'Noto Sans SC', 'PingFang SC', 'Inter', -apple-system, sans-serif;
  --mono:  'JetBrains Mono', ui-monospace, 'SF Mono', Menlo, monospace;
 }
 *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
 body {
  font-family: var(--sans);
  color: var(--ink);
  background: linear-gradient(135deg, var(--bg-top) 0%, var(--bg-bot) 100%);
  padding: 40px 64px 32px;
  -webkit-font-smoothing: antialiased;
  font-feature-settings: "kern" 1, "liga" 1, "cv02" 1, "cv11" 1;
 }
 .page {
  max-width: 1560px;
  margin: 0 auto;
 }
 /* ── header ─────────────────────────────────────────── */
 .eyebrow {
  font-family: var(--sans);
  font-size: 12px;
  font-weight: 500;
  letter-spacing: 0.22em;
  color: var(--muted);
  text-transform: uppercase;
  margin-bottom: 10px;
 }
 .eyebrow.cn { font-family: var(--cn); letter-spacing: 0.4em; text-transform: none; }
 h1 {
  font-family: var(--sans);
  font-size: 40px;
  font-weight: 600;
  letter-spacing: -0.02em;
  line-height: 1.15;
  color: var(--ink);
  margin-bottom: 88px;
 }
 h1.cn { font-family: var(--cn); letter-spacing: 0.02em; font-weight: 600; }
 /* ── diagram frame ──────────────────────────────────── */
 .diagram { position: relative; }
 .section-label {
  font-family: var(--sans);
  font-size: 11px;
  font-weight: 500;
  letter-spacing: 0.22em;
  color: var(--muted);
  text-transform: uppercase;
  text-align: center;
  margin-bottom: 20px;
 }
 .section-label.cn { font-family: var(--cn); letter-spacing: 0.4em; text-transform: none; font-size: 12px; }
 .section-label.bottom { margin: 20px 0 0; }
 /* ── card rows ──────────────────────────────────────── */
 .row {
  display: flex;
  gap: 12px;
  justify-content: center;
  width: 96%;
  margin: 0 auto;
  position: relative;
 }
 .row.top .card { flex: 1; }
 .row.bottom {
  gap: 0;
  justify-content: space-between;
 }
 /* flex: 0 0 auto so cards keep their intrinsic (nowrap) width and
   neighbouring card backgrounds cannot clip a description. */
 .row.bottom .card { flex: 0 0 auto; }
 .card {
  background: var(--card-bg);
  border: 1px solid var(--card-bd);
  border-radius: 6px;
  padding: 14px 10px;
  text-align: center;
  min-width: 0;
  position: relative;
 }
 .card .name {
  font-family: var(--mono);
  font-size: 13px;
  font-weight: 500;
  color: var(--ink);
  line-height: 1.2;
  white-space: nowrap;
  display: block;
 }
 .card .desc {
  font-family: var(--sans);
  font-size: 11px;
  font-weight: 400;
  color: var(--muted);
  margin-top: 4px;
  line-height: 1.3;
  min-height: 28px;
  white-space: nowrap;
 }
 .card .desc.cn { font-family: var(--cn); }
 .row.bottom .card { padding: 10px 6px; }
 .row.bottom .card .name { font-size: 10px; }
 .row.bottom .card .desc { font-size: 9px; min-height: 22px; }
 .row.bottom .card .desc.cn { font-size: 10px; }
 /* connectors — pure CSS, guaranteed vertical & parallel */
 .row.top    .card::after,
 .row.bottom .card::before {
  content: '';
  position: absolute;
  left: 50%;
  transform: translateX(-50%);
  width: 2px;
  background: var(--brand);
 }
 .row.top    .card::after  { top: 100%; height: 40px; }
 .row.bottom .card::before { bottom: 100%; height: 40px; }
 /* ── bus row (Cordis) ───────────────────────────────── */
 .bus-row {
  position: relative;
  width: 96%;
  margin: 40px auto;
 }
 .bus {
  height: 60px;
  background: var(--brand);
  color: #ffffff;
  border-radius: 8px;
  display: flex;
  align-items: center;
  justify-content: center;
  font-family: var(--sans);
  font-size: 18px;
  font-weight: 500;
  letter-spacing: 0.01em;
 }
 .bus .dot { padding: 0 12px; opacity: 0.75; }
 .bus .vendored {
  font-family: var(--mono);
  font-size: 15px;
  font-weight: 400;
  opacity: 0.8;
  margin-left: 8px;
 }
 .bus.cn .core { font-family: var(--cn); }
 /* ── cordis.yml side box (positioned outside bus width) ─ */
 .yml-side {
  position: absolute;
  left: calc(100% + 20px);
  top: 50%;
  transform: translateY(-50%);
  width: 130px;
  display: flex;
  flex-direction: column;
  align-items: flex-start;
 }
 .yml-arrow {
  position: absolute;
  left: -30px;
  top: 50%;
  transform: translateY(-50%);
  width: 30px;
  height: 12px;
 }
 .yml-arrow svg { display: block; }
 .yml-box {
  width: 100%;
  background: var(--card-bg);
  border: 1px solid var(--card-bd);
  border-radius: 6px;
  padding: 12px 10px;
  text-align: center;
 }
 .yml-box .file {
  font-family: var(--mono);
  font-size: 13px;
  font-weight: 500;
  color: var(--ink);
 }
 .yml-box .sub {
  font-family: var(--sans);
  font-size: 10px;
  color: var(--muted);
  margin-top: 4px;
  line-height: 1.3;
 }
 .yml-box .sub.cn { font-family: var(--cn); letter-spacing: 0.05em; }
 .yml-note {
  font-family: var(--sans);
  font-size: 10px;
  color: var(--muted);
  margin-top: 10px;
  width: 100%;
  text-align: center;
  line-height: 1.4;
 }
 .yml-note.cn { font-family: var(--cn); letter-spacing: 0.05em; }
@@ -1,97 +0,0 @@
 #!/bin/bash
 # render.sh — Chrome headless renderer for the DeepSeek Harness architecture diagram.
 #
 # Writes arch-en.png and arch-zh.png (3072×1160, ~600 KB each) to the given output
 # directory. Default is <repo>/assets/, which is where the README image references
 # resolve.
 #
 # Usage:
 #   bash render.sh                    # writes to <repo>/assets/
 #   bash render.sh /some/other/dir    # writes there instead
 #
 # Env overrides:
 #   CHROME=/path/to/Chrome       # non-standard Chrome location
 #   PORT=<n>                     # override the local http.server port
 set -e
 SKILL_DIR="$(cd "$(dirname "$0")" && pwd)"
 REPO_ROOT="$(cd "$SKILL_DIR/../../.." && pwd)"
 OUT_DIR="${1:-$REPO_ROOT/assets}"
 BIND_PORT="${PORT:-0}"   # 0 → kernel picks a free port
 SERVER_LOG="$(mktemp -t dsh-arch-diagram-server.XXXXXX.log)"
 # Locate a Chrome / Chromium binary. Honour $CHROME if set; otherwise probe
 # common per-platform paths so `bash render.sh` works on macOS + Linux out
 # of the box.
 if [ -z "$CHROME" ]; then
  for candidate in \
    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
    "/Applications/Chromium.app/Contents/MacOS/Chromium" \
    "$(command -v google-chrome 2>/dev/null || true)" \
    "$(command -v google-chrome-stable 2>/dev/null || true)" \
    "$(command -v chromium 2>/dev/null || true)" \
    "$(command -v chromium-browser 2>/dev/null || true)"; do
    if [ -n "$candidate" ] && [ -x "$candidate" ]; then
      CHROME="$candidate"; break
    fi
  done
 fi
 if [ -z "$CHROME" ] || [ ! -x "$CHROME" ]; then
  echo "No Chrome / Chromium binary found." >&2
  echo "Tried: macOS default, google-chrome, google-chrome-stable, chromium, chromium-browser." >&2
  echo "Set CHROME=/path/to/binary and rerun." >&2
  exit 1
 fi
 mkdir -p "$OUT_DIR"
 python3 -u -m http.server "$BIND_PORT" --bind 127.0.0.1 --directory "$SKILL_DIR" \
  >"$SERVER_LOG" 2>&1 &
 SERVER_PID=$!
 cleanup() { kill "$SERVER_PID" 2>/dev/null; rm -f "$SERVER_LOG"; }
 trap cleanup EXIT INT TERM
 # Discover the actual bound port from Python's own startup line
 # ("Serving HTTP on 127.0.0.1 port <N> ..."). Works whether the kernel
 # picked it or PORT was set explicitly; no external `lsof` needed.
 PORT=""
 for _ in $(seq 1 40); do
  PORT=$(awk '/Serving HTTP on/ {print $6; exit}' "$SERVER_LOG" 2>/dev/null || true)
  [ -n "$PORT" ] && break
  # Bail early if the server died (e.g. explicit PORT already in use).
  kill -0 "$SERVER_PID" 2>/dev/null || break
  sleep 0.05
 done
 if [ -z "$PORT" ]; then
  echo "Failed to detect local server port. Server log:" >&2
  cat "$SERVER_LOG" >&2 || true
  exit 1
 fi
 # Chrome/Chromium refuses to run as root without --no-sandbox. Rendering
 # a local static HTML doc under a headless browser doesn't need Chrome's
 # own sandbox, so passing the flag when EUID is 0 makes the script work
 # in Codex/CI container environments that default to root.
 CHROME_EXTRA_ARGS=()
 if [ "$(id -u)" = "0" ]; then
  CHROME_EXTRA_ARGS+=(--no-sandbox)
 fi
 for lang in en zh; do
  out="$OUT_DIR/arch-$lang.png"
  "$CHROME" \
    "${CHROME_EXTRA_ARGS[@]}" \
    --headless=new \
    --disable-gpu \
    --hide-scrollbars \
    --force-device-scale-factor=2 \
    --window-size=1820,580 \
    --virtual-time-budget=8000 \
    --screenshot="$out" \
    "http://127.0.0.1:$PORT/harness-arch-$lang.html" \
    2>/dev/null
  size=$(du -h "$out" | awk '{print $1}')
  echo "[$lang] wrote $out ($size)"
 done
@@ -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.md: a32ad5cddd2bcaa9468031e5833aab8e78dac52b
-README.zh.md: cf029cc0bb8c5aa527d14753803eac4c28ab9de7
+README.zh.md: 4ffb222b2f2bff8c41ac42c047ea034e4416d4d7
@@ -2,32 +2,70 @@
 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, 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. The installer requires `git` and Node `^22.19 || >=24`, offers to install `pnpm` when it is missing, and prompts for a DeepSeek API key:
 ```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 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 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).
 - **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
+pnpm run test:coverage
 # 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
 ```
-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), read the [architecture](docs/architecture.md) before changing packages, and follow [AGENTS.md](AGENTS.md) when working in this repository.
-For agents, follow [AGENTS.md](AGENTS.md).
+DeepSeek Harness is currently pre-release.
 ## License
 [BSD 3-Clause](LICENSE)
@@ -2,32 +2,74 @@
 [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`。安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥：
 ```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)。
+安装器会将 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)。
 ## 社区
 扫描二维码加入 DeepSeek Harness 微信社区。
 <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
+pnpm run test:coverage
 # 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
 ```
-面向开发者：先读[开发指南](docs/development.md)，了解本地环境搭建、钩子、环境变量与质量门禁，动手改 package 之前再读[架构设计](docs/architecture.md)和[文档关系图索引](docs/graph-atlas.md)。局部上下文见 [packages/](packages/) 与 [vendor/](vendor/)。
+请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)；在本仓库工作时，请遵循 [AGENTS.md](AGENTS.md)。
-面向 agent：遵循 [AGENTS.md](AGENTS.md)。
+DeepSeek Harness 目前处于预发布阶段。
 ## 许可证
 [BSD 3-Clause](LICENSE)