dsh-plugin-dev-kb 1.0.9 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [1.3.0] - 2026-09-10
+
+- 修复：移除每次加载覆写 `state.json` 的调试残留（纯数据插件本不需要持久化状态）；
+- 改进：日志改用 `ctx.logger` 标准输出；
+- 改进：清理逻辑改为 `ctx.effect` 标准模式（插件卸载自动撤销，零残留）；
+- 文档：相关插件段补齐 dsh-plugin-context-trim 行（修复表格断行）；npm files 补 `docs/`（README 引用的 banner）。
+
+## [1.2.0] - 2026-09-10
+
+- 知识库同步至上游 master `aa8262ec`（2026-09-10，距上次基线 `d347e703` 跨 1167 个 commit）：
+  站点镜像 184 → 188 页（中英 94/94）；上游 docs 重构进 `docs/user/` 子目录（发布清单
+  `website/docs.ts` 照常投影，站点路由不变）。
+- 补充文档 58 → 62 篇：新增 `cookbook/adding-a-session-format-version`（会话格式版本号新增流程，
+  中英一对）与 `session-format-status`（会话格式状态，中英一对）。
+- 更新 `kb/meta/source.json` 与 `site-pages.txt`；重建检索索引（245 → 253 文件）与 INDEX.md。
+
+## [1.1.0] - 2026-09-05
+
+- 知识库同步至上游 master `d347e703`（2026-09-05，对应 dsh `0.1.2-rc.1`）：站点镜像 182 → 184 页
+  （中英 92/92），89 页内容更新（config-catalog / tool-catalog / api-gateway / 全部 46 个子系统页 /
+  cookbook 3 篇 / guide providers+schedule / cordis-tutorial 07 / llm-adapter 等）；
+  新增 `guide/network-proxy`（代理后运行 DSH，中英一对）。
+- 补充文档 56 → 58 篇：新增 `cookbook/adding-a-remote-api`（ctx.remote 端点五步操作，中英一对）。
+- 更新 `kb/meta/source.json` 与 `site-pages.txt`；重建检索索引（241 → 245 文件）与 INDEX.md；
+  `topics.md` 新增 network-proxy 入口与 adding-a-remote-api 扩展条目。
+
 ## [1.0.9] - 2026-08-30
 
 - 知识库同步至上游 master `cd5ef814`（2026-08-30）：站点镜像 168 → 182 页（中英 91/91），

package/README.en.md

@@ -1,12 +1,18 @@
-[中文](./README.md) | **English**
+<p align="center">
+  <img src="docs/banner.svg" alt="dsh-plugin-dev-kb banner" width="100%">
+</p>
 
 # dsh-plugin-dev-kb
 
 ![npm version](https://img.shields.io/npm/v/dsh-plugin-dev-kb)
+![npm downloads](https://img.shields.io/npm/dm/dsh-plugin-dev-kb)
 ![License](https://img.shields.io/github/license/Pasumao/dsh-plugin-dev-kb)
+![Stars](https://img.shields.io/github/stars/Pasumao/dsh-plugin-dev-kb?style=social)
 ![AI Assisted](https://img.shields.io/badge/AI-Assisted-8A2BE2)
 
-> **182-page official mirror · 56 supplementary docs · 241-file search index · 0 runtime dependencies**
+[中文](./README.md) | **English**
+
+> **188-page official mirror · 62 supplementary docs · 253-file search index · 0 runtime dependencies**
 
 **The official docs at your side whenever you write dsh plugins**: the entire content of the DeepSeek Harness official documentation site
 <https://deepseek-harness.github.io/deepseek-harness/> is organized into a form natively usable by dsh —
@@ -15,16 +21,16 @@ once this plugin is installed, the agent automatically loads the knowledge base
 ## What is this
 
 - **Complete site mirror**: the official docs (VitePress) are generated as a projection of the raw Markdown in
-  `docs/` of the `deepseek-ai/deepseek-harness` repository (links rewritten to site routes, verbatim identical to the live site). 182 pages in both Chinese and English.
-- **Supplementary docs**: 56 development references from the repo's `docs/` that were not published to the site (glossary, defensive patterns, module graph, testing strategy, incident postmortems, i18n specs, etc.).
+  `docs/` of the `deepseek-ai/deepseek-harness` repository (links rewritten to site routes, verbatim identical to the live site). 188 pages in both Chinese and English.
+- **Supplementary docs**: 62 development references from the repo's `docs/` that were not published to the site (glossary, defensive patterns, module graph, testing strategy, incident postmortems, i18n specs, etc.).
 - **Agent-friendly**: the `skills/dsh-plugin-dev-kb.md` skill lets dsh auto-load it during plugin development tasks, providing the knowledge base location,
   topic navigation, and search strategy; `kb/meta/topics.md` maps task scenarios to the files to read; `kb/meta/search-index.json` provides full search coverage.
 
 ## Features
 
 - **Complete mirror of the official docs**: the entire content of the deepseek-ai/deepseek-harness official documentation site, organized into a form natively usable by dsh,
-  182 pages in both Chinese and English, links rewritten to site routes, verbatim identical to the live site;
-- **Repo supplementary docs**: 56 development references not published to the site (glossary, defensive patterns, module graph, testing strategy, incident postmortems, i18n specs, etc.);
+  188 pages in both Chinese and English, links rewritten to site routes, verbatim identical to the live site;
+- **Repo supplementary docs**: 62 development references not published to the site (glossary, defensive patterns, module graph, testing strategy, incident postmortems, i18n specs, etc.);
 - **Agent-friendly**: the `dsh-plugin-dev-kb` skill lets dsh auto-load the knowledge base during plugin development tasks;
   `kb/meta/topics.md` maps task scenarios to the files to read, and `kb/meta/search-index.json` provides full search coverage;
 - **Human-usable**: browse the `kb/` directory directly, or open `kb/INDEX.md` to look things up by URL mapping;
@@ -90,7 +96,7 @@ dsh-plugin-dev-kb/
 │   ├── extra/         repo supplementary docs: glossary, defensive-patterns, module-graph, postmortem/, i18n/ …
 │   ├── meta/
 │   │   ├── topics.md         ★ topic navigation: task scenario → files
-│   │   ├── search-index.json full index (241 files)
+│   │   ├── search-index.json full index (253 files)
 │   │   ├── source.json       source commit / time / stats
 │   │   └── site-pages.txt    list of live site pages
 │   ├── INDEX.md        site URL ↔ local file mapping
@@ -131,7 +137,7 @@ This plugin is part of **Pasumao's dsh plugin ecosystem**; other published plugi
 | [dsh-plugin-table-zoom](https://www.npmjs.com/package/dsh-plugin-table-zoom) | [GitHub repo](https://github.com/Pasumao/dsh-plugin-table-zoom) | Floating viewer for long chat tables + one-click copy as Markdown |
 | [dsh-plugin-windows-guard](https://www.npmjs.com/package/dsh-plugin-windows-guard) | [GitHub repo](https://github.com/Pasumao/dsh-plugin-windows-guard) | Windows environment pitfall prevention: rule skills + mojibake detection / dangerous-write interception / encoding diagnosis & repair |
 | [dsh-plugin-workbench](https://www.npmjs.com/package/dsh-plugin-workbench) | [GitHub repo](https://github.com/Pasumao/dsh-plugin-workbench) | VS Code-style file explorer + editable preview |
-
+| [dsh-plugin-context-trim](https://www.npmjs.com/package/dsh-plugin-context-trim) | [GitHub](https://github.com/Pasumao/dsh-plugin-context-trim) | Per-session injection gate: trim skills / tools / prompt sections |
 > See [Pasumao · dsh plugins](https://github.com/Pasumao) for the rest of the series; if you find them useful, a ⭐ on GitHub is much appreciated.
 
 ## AI-generated content statement

package/README.md

@@ -1,12 +1,18 @@
+<p align="center">
+  <img src="docs/banner.svg" alt="dsh-plugin-dev-kb banner" width="100%">
+</p>
+
 # dsh-plugin-dev-kb
 
 ![npm version](https://img.shields.io/npm/v/dsh-plugin-dev-kb)
+![npm downloads](https://img.shields.io/npm/dm/dsh-plugin-dev-kb)
 ![License](https://img.shields.io/github/license/Pasumao/dsh-plugin-dev-kb)
+![Stars](https://img.shields.io/github/stars/Pasumao/dsh-plugin-dev-kb?style=social)
 ![AI Assisted](https://img.shields.io/badge/AI-Assisted-8A2BE2)
 
 [**中文**](./README.md) | [English](./README.en.md)
 
-> **182 页官方镜像 · 56 篇补充文档 · 241 文件搜索索引 · 0 运行时依赖**
+> **188 页官方镜像 · 62 篇补充文档 · 253 文件搜索索引 · 0 运行时依赖**
 
 **写 dsh 插件时的随身官方文档**：把 DeepSeek Harness 官方文档站点
 <https://deepseek-harness.github.io/deepseek-harness/> 的全部内容整理为 dsh 原生可用的形态——
@@ -15,16 +21,16 @@
 ## 这是什么
 
 - **站点完整镜像**：官方文档（VitePress）由仓库 `deepseek-ai/deepseek-harness` 的 `docs/` 原始 Markdown
-  投影生成（链接已按站点路由重写，与线上逐字一致）。中英双语共 182 页。
-- **补充文档**：仓库 `docs/` 中未发布到站点的 56 篇开发参考（术语表、防御模式、模块图、测试策略、事故复盘、i18n 规范等）。
+  投影生成（链接已按站点路由重写，与线上逐字一致）。中英双语共 188 页。
+- **补充文档**：仓库 `docs/` 中未发布到站点的 62 篇开发参考（术语表、防御模式、模块图、测试策略、事故复盘、i18n 规范等）。
 - **agent 友好**：`skills/dsh-plugin-dev-kb.md` 技能让 dsh 在插件开发任务中自动加载，获知知识库位置、
   主题导航与检索策略；`kb/meta/topics.md` 按任务场景映射要读的文件；`kb/meta/search-index.json` 提供全量检索。
 
 ## 功能
 
 - **官方文档完整镜像**：deepseek-ai/deepseek-harness 官方文档站全部内容整理为 dsh 原生可用的形态，
-  中英双语共 182 页，链接按站点路由重写，与线上逐字一致；
-- **仓库补充文档**：未发布到站点的 56 篇开发参考（术语表、防御模式、模块图、测试策略、事故复盘、i18n 规范等）；
+  中英双语共 188 页，链接按站点路由重写，与线上逐字一致；
+- **仓库补充文档**：未发布到站点的 62 篇开发参考（术语表、防御模式、模块图、测试策略、事故复盘、i18n 规范等）；
 - **agent 友好**：`dsh-plugin-dev-kb` 技能让 dsh 在插件开发任务中自动加载知识库；
   `kb/meta/topics.md` 按任务场景映射要读的文件，`kb/meta/search-index.json` 提供全量检索；
 - **人侧可用**：直接浏览 `kb/` 目录，或打开 `kb/INDEX.md` 按 URL 对照查阅；
@@ -90,7 +96,7 @@ dsh-plugin-dev-kb/
 │   ├── extra/         仓库补充文档：glossary、defensive-patterns、module-graph、postmortem/、i18n/ …
 │   ├── meta/
 │   │   ├── topics.md         ★ 主题导航：任务场景 → 文件
-│   │   ├── search-index.json 全量索引（241 文件）
+│   │   ├── search-index.json 全量索引（253 文件）
 │   │   ├── source.json       来源 commit / 时间 / 统计
 │   │   └── site-pages.txt    线上页面清单
 │   ├── INDEX.md        站点 URL ↔ 本地文件 对照
@@ -131,7 +137,7 @@ npm run selfcheck   # 结构完整 + 入口 / bundle patch 存在性
 | [dsh-plugin-table-zoom](https://www.npmjs.com/package/dsh-plugin-table-zoom) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-table-zoom) | 聊天长表格浮窗查看 + 一键复制 Markdown |
 | [dsh-plugin-windows-guard](https://www.npmjs.com/package/dsh-plugin-windows-guard) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-windows-guard) | Windows 环境防坑：守则技能 + 乱码检测 / 危险写拦截 / 编码诊断修复 |
 | [dsh-plugin-workbench](https://www.npmjs.com/package/dsh-plugin-workbench) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-workbench) | VS Code 风格文件浏览器 + 可编辑预览 |
-
+| [dsh-plugin-context-trim](https://www.npmjs.com/package/dsh-plugin-context-trim) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-context-trim) | 会话注入门控：skill / tool / 提示词段落按会话裁剪 |
 > 本系列其余插件见 [Pasumao · dsh 插件](https://github.com/Pasumao)；觉得好用欢迎到 GitHub 点 ⭐。
 
 ## AI 生成声明
@@ -141,4 +147,4 @@ npm run selfcheck   # 结构完整 + 入口 / bundle patch 存在性
 
 ## License
 
-MIT
+[MIT](./LICENSE)

package/docs/banner.svg

@@ -0,0 +1,25 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="260" viewBox="0 0 1200 260" role="img" aria-label="dsh-plugin-dev-kb banner">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#0a1830"/>
+      <stop offset="1" stop-color="#102a4c"/>
+    </linearGradient>
+    <radialGradient id="glow" cx="0.85" cy="0.1" r="0.9">
+      <stop offset="0" stop-color="#FBBF24" stop-opacity="0.22"/>
+      <stop offset="1" stop-color="#FBBF24" stop-opacity="0"/>
+    </radialGradient>
+    <linearGradient id="whale" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#ffffff"/>
+      <stop offset="1" stop-color="#cfe3ff"/>
+    </linearGradient>
+  </defs>
+  <rect width="1200" height="260" rx="18" fill="url(#bg)"/>
+  <rect width="1200" height="260" rx="18" fill="url(#glow)"/>
+  <rect x="0" y="0" width="1200" height="6" rx="3" fill="#FBBF24" opacity="0.85"/>
+  <g transform="translate(64,80) scale(2.0)">
+    <path d="M48.8354 10.0479C48.3232 9.79199 48.1025 10.2798 47.8032 10.5278C47.7007 10.6079 47.6143 10.7119 47.5273 10.8076C46.7793 11.624 45.9048 12.1597 44.7622 12.0957C43.0923 12 41.666 12.5356 40.4058 13.8398C40.1377 12.2319 39.2476 11.272 37.8926 10.6558C37.1836 10.3359 36.4668 10.0156 35.9702 9.31982C35.6235 8.82373 35.5293 8.27197 35.356 7.72754C35.2456 7.3999 35.1353 7.06396 34.7651 7.00781C34.3633 6.94385 34.2056 7.2876 34.0479 7.57568C33.418 8.75195 33.1733 10.0479 33.1973 11.3599C33.2524 14.312 34.4736 16.6641 36.8999 18.3359C37.1758 18.5278 37.2466 18.7197 37.1597 19C36.9946 19.5757 36.7974 20.1357 36.624 20.7119C36.5137 21.0801 36.3486 21.1597 35.9624 21C34.6309 20.4321 33.481 19.5918 32.4644 18.5757C30.7393 16.8721 29.1792 14.9917 27.2334 13.52C26.7764 13.1758 26.3193 12.856 25.8467 12.5518C23.8618 10.584 26.1069 8.96777 26.627 8.77588C27.1704 8.57568 26.8159 7.8877 25.0591 7.896C23.3022 7.90381 21.6953 8.50391 19.647 9.30371C19.3477 9.42383 19.0322 9.51172 18.7095 9.58398C16.8501 9.22363 14.9199 9.14355 12.9033 9.37598C9.10596 9.80762 6.07275 11.6396 3.84326 14.7681C1.16455 18.5278 0.53418 22.7998 1.30664 27.2559C2.11768 31.9521 4.46582 35.8398 8.07373 38.8799C11.8159 42.0322 16.1255 43.5762 21.041 43.2803C24.0269 43.104 27.3516 42.6963 31.1016 39.4561C32.0469 39.936 33.0396 40.1279 34.686 40.272C35.9546 40.3921 37.1758 40.208 38.1211 40.0078C39.6021 39.688 39.4995 38.2881 38.9639 38.0322C34.623 35.9678 35.5762 36.8081 34.71 36.1279C36.9155 33.4639 40.2402 30.6958 41.54 21.728C41.6426 21.0161 41.5557 20.5679 41.54 19.9917C41.5322 19.6396 41.6108 19.5039 42.0049 19.4639C43.0923 19.3359 44.1479 19.0317 45.1167 18.4878C47.9292 16.9199 49.064 14.3438 49.3315 11.2559C49.3711 10.7837 49.3237 10.2959 48.8354 10.0479ZM24.3262 37.8398C20.1196 34.4639 18.0791 33.3521 17.2358 33.3999C16.4482 33.4482 16.5898 34.3682 16.7632 34.9678C16.9443 35.5601 17.1812 35.9683 17.5117 36.4878C17.7402 36.832 17.8979 37.3442 17.2832 37.728C15.9282 38.584 13.5728 37.4399 13.4624 37.3838C10.7207 35.7358 8.42822 33.5601 6.81348 30.584C5.25342 27.7197 4.34766 24.6479 4.19775 21.3677C4.1582 20.5757 4.38672 20.2959 5.15869 20.1519C6.17529 19.96 7.22314 19.9199 8.23926 20.0718C12.5327 20.7119 16.1885 22.6719 19.2529 25.7759C21.002 27.5439 22.3252 29.6558 23.6885 31.7202C25.1377 33.9121 26.6978 36 28.6831 37.7119C29.3843 38.312 29.9434 38.7681 30.479 39.104C28.8643 39.2881 26.1699 39.3281 24.3262 37.8398ZM26.3433 24.6001C26.3433 24.248 26.6191 23.9678 26.9658 23.9678C27.0444 23.9678 27.1152 23.9839 27.1782 24.0078C27.2651 24.04 27.3438 24.0879 27.4067 24.1602C27.5171 24.272 27.5801 24.4321 27.5801 24.6001C27.5801 24.9521 27.3042 25.2319 26.9575 25.2319C26.6108 25.2319 26.3433 24.9521 26.3433 24.6001ZM32.6064 27.8799C32.2046 28.0479 31.8027 28.1919 31.4165 28.208C30.8179 28.2397 30.1641 27.9922 29.8096 27.688C29.2583 27.2158 28.8643 26.9521 28.6987 26.1279C28.6279 25.7759 28.6675 25.2319 28.7305 24.9199C28.8721 24.248 28.7144 23.8159 28.2495 23.4238C27.8716 23.104 27.3911 23.0161 26.8633 23.0161C26.666 23.0161 26.4849 22.9277 26.3511 22.856C26.1304 22.7441 25.9492 22.4639 26.1226 22.1201C26.1777 22.0078 26.4458 21.7358 26.5088 21.688C27.2256 21.272 28.0527 21.4077 28.8169 21.7197C29.5259 22.0161 30.0615 22.5601 30.834 23.3281C31.6216 24.2559 31.7632 24.5117 32.2124 25.208C32.5669 25.752 32.8901 26.312 33.1104 26.9521C33.2446 27.3521 33.0713 27.6802 32.6064 27.8799Z" fill="url(#whale)"/>
+  </g>
+  <text x="212" y="86" font-family="'Segoe UI','PingFang SC','Microsoft YaHei',sans-serif" font-size="17" font-weight="600" letter-spacing="5" fill="#FBBF24">DEEPSEEK HARNESS · DSH PLUGIN</text>
+  <text x="212" y="152" font-family="ui-monospace,'Cascadia Code',Consolas,monospace" font-size="46" font-weight="700" fill="#f4f8ff">dsh-plugin-dev-kb</text>
+  <text x="212" y="204" font-family="'Segoe UI','PingFang SC','Microsoft YaHei',sans-serif" font-size="22" fill="#9fb3c8">官方文档完整镜像 · 188 页 · 主题导航 · agent 自动加载</text>
+</svg>

package/kb/INDEX.md

@@ -1,6 +1,6 @@
 # DeepSeek Harness 文档索引
 
-> 由 `scripts/rebuild-index.mjs` 自动生成。共 182 个站点页面（中英双语），另有 56 个补充文档在 `extra/`。
+> 由 `scripts/rebuild-index.mjs` 自动生成。共 188 个站点页面（中英双语），另有 62 个补充文档在 `extra/`。
 
 ## 中文站点（根路径）
 
@@ -16,6 +16,7 @@
 | --- | --- | --- |
 | 通过 GitHub Webhook 创建评审会话 | [https://deepseek-harness.github.io/deepseek-harness/guide/github-review](https://deepseek-harness.github.io/deepseek-harness/guide/github-review) | `site/guide/github-review.md` |
 | 连接第三方记忆 MCP 服务 | [https://deepseek-harness.github.io/deepseek-harness/guide/mcp-memory](https://deepseek-harness.github.io/deepseek-harness/guide/mcp-memory) | `site/guide/mcp-memory.md` |
+| 在网络代理后面运行 DSH | [https://deepseek-harness.github.io/deepseek-harness/guide/network-proxy](https://deepseek-harness.github.io/deepseek-harness/guide/network-proxy) | `site/guide/network-proxy.md` |
 | 配置模型 | [https://deepseek-harness.github.io/deepseek-harness/guide/providers](https://deepseek-harness.github.io/deepseek-harness/guide/providers) | `site/guide/providers.md` |
 | Python SDK 入门 | [https://deepseek-harness.github.io/deepseek-harness/guide/python-sdk](https://deepseek-harness.github.io/deepseek-harness/guide/python-sdk) | `site/guide/python-sdk.md` |
 | 使用 Web UI | [https://deepseek-harness.github.io/deepseek-harness/guide/quickstart](https://deepseek-harness.github.io/deepseek-harness/guide/quickstart) | `site/guide/quickstart.md` |
@@ -68,6 +69,7 @@
 | 会话持久化事件目录 | [https://deepseek-harness.github.io/deepseek-harness/reference/persistence-catalog](https://deepseek-harness.github.io/deepseek-harness/reference/persistence-catalog) | `site/reference/persistence-catalog.md` |
 | 用户审批 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/approval](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/approval) | `site/reference/subsystems/approval.md` |
 | Client 模块 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/client-modules](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/client-modules) | `site/reference/subsystems/client-modules.md` |
+| 客户端资源 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/client-resources](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/client-resources) | `site/reference/subsystems/client-resources.md` |
 | 代码运行时 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/code-runtime](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/code-runtime) | `site/reference/subsystems/code-runtime.md` |
 | 用户命令 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/commands](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/commands) | `site/reference/subsystems/commands.md` |
 | 压缩（compaction） | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/compaction](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/compaction) | `site/reference/subsystems/compaction.md` |
@@ -95,6 +97,7 @@
 | 会话 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/session](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/session) | `site/reference/subsystems/session.md` |
 | 用户设置 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/settings](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/settings) | `site/reference/subsystems/settings.md` |
 | Bash 执行器 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/shell](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/shell) | `site/reference/subsystems/shell.md` |
+| 右侧 Sidebar | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/sidebar-right](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/sidebar-right) | `site/reference/subsystems/sidebar-right.md` |
 | Skills | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/skills](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/skills) | `site/reference/subsystems/skills.md` |
 | Web Client Slots | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/slots](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/slots) | `site/reference/subsystems/slots.md` |
 | spill 存储 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/spill](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/spill) | `site/reference/subsystems/spill.md` |
@@ -147,6 +150,7 @@
 | LLM adapters | [https://deepseek-harness.github.io/deepseek-harness/en/develop/practice/llm-adapter](https://deepseek-harness.github.io/deepseek-harness/en/develop/practice/llm-adapter) | `site/en/develop/practice/llm-adapter.md` |
 | Create review Sessions from GitHub webhooks | [https://deepseek-harness.github.io/deepseek-harness/en/guide/github-review](https://deepseek-harness.github.io/deepseek-harness/en/guide/github-review) | `site/en/guide/github-review.md` |
 | Connect a third-party memory MCP server | [https://deepseek-harness.github.io/deepseek-harness/en/guide/mcp-memory](https://deepseek-harness.github.io/deepseek-harness/en/guide/mcp-memory) | `site/en/guide/mcp-memory.md` |
+| Run DSH behind a network proxy | [https://deepseek-harness.github.io/deepseek-harness/en/guide/network-proxy](https://deepseek-harness.github.io/deepseek-harness/en/guide/network-proxy) | `site/en/guide/network-proxy.md` |
 | Configure models | [https://deepseek-harness.github.io/deepseek-harness/en/guide/providers](https://deepseek-harness.github.io/deepseek-harness/en/guide/providers) | `site/en/guide/providers.md` |
 | Get started with the Python SDK | [https://deepseek-harness.github.io/deepseek-harness/en/guide/python-sdk](https://deepseek-harness.github.io/deepseek-harness/en/guide/python-sdk) | `site/en/guide/python-sdk.md` |
 | Use the Web UI | [https://deepseek-harness.github.io/deepseek-harness/en/guide/quickstart](https://deepseek-harness.github.io/deepseek-harness/en/guide/quickstart) | `site/en/guide/quickstart.md` |
@@ -171,6 +175,7 @@
 | Session Persistence Event Catalog | [https://deepseek-harness.github.io/deepseek-harness/en/reference/persistence-catalog](https://deepseek-harness.github.io/deepseek-harness/en/reference/persistence-catalog) | `site/en/reference/persistence-catalog.md` |
 | User Approval | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/approval](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/approval) | `site/en/reference/subsystems/approval.md` |
 | Client Modules | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/client-modules](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/client-modules) | `site/en/reference/subsystems/client-modules.md` |
+| Client Resources | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/client-resources](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/client-resources) | `site/en/reference/subsystems/client-resources.md` |
 | Code Runtime | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/code-runtime](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/code-runtime) | `site/en/reference/subsystems/code-runtime.md` |
 | Human Commands | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/commands](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/commands) | `site/en/reference/subsystems/commands.md` |
 | Compaction | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/compaction](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/compaction) | `site/en/reference/subsystems/compaction.md` |
@@ -198,6 +203,7 @@
 | Sessions | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/session](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/session) | `site/en/reference/subsystems/session.md` |
 | User Settings | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/settings](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/settings) | `site/en/reference/subsystems/settings.md` |
 | Bash Executor | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/shell](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/shell) | `site/en/reference/subsystems/shell.md` |
+| Right Sidebar | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/sidebar-right](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/sidebar-right) | `site/en/reference/subsystems/sidebar-right.md` |
 | Skills | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/skills](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/skills) | `site/en/reference/subsystems/skills.md` |
 | Web Client Slots | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/slots](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/slots) | `site/en/reference/subsystems/slots.md` |
 | Spill Storage | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/spill](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/spill) | `site/en/reference/subsystems/spill.md` |
@@ -220,5 +226,5 @@
 
 ---
 
-*站点页面：182（中文 91，英文 91）*
+*站点页面：188（中文 94，英文 94）*
 

package/kb/README.md

@@ -28,7 +28,7 @@ knowledge/deepseek-harness/
 │   └── i18n/               文档双语规范与术语
 └── meta/
     ├── source.json         来源信息：仓库 commit、抓取时间、统计
-    └── site-pages.txt      线上站点页面清单（由投影结果生成，182 页）
+    └── site-pages.txt      线上站点页面清单（由投影结果生成，188 页）
 ```
 
 ## 插件开发学习路径（从 `site/` 开始）
@@ -76,6 +76,6 @@ node scripts/rebuild-index.mjs
 
 ## 统计
 
-- 站点页面：182 个 Markdown（中文 91 + 英文 91），4 张图片
-- 补充文档：56 个 Markdown（`extra/`）
-- 来源 commit：`cd5ef8148158c3a752a658978873241fdf8e2bbc`（master）
+- 站点页面：188 个 Markdown（中文 94 + 英文 94），4 张图片
+- 补充文档：62 个 Markdown（`extra/`）
+- 来源 commit：`aa8262ec091698bae9a6b04773a6b5b06ad4aef2`（master，2026-09-10 同步）

package/kb/extra/AGENTS.md

@@ -35,7 +35,7 @@ Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookb
 
 ## Writing rules
 
-- **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, Agent Notes, or postmortems; the latter two may cite merged PRs and issues as evidence.
+- **Document current state, not change history.** Name live mechanisms, not PRs, commits, stack positions, or "previously/now/no longer". Keep history in commits, PRs, Agent Notes, or postmortems. General Session-format prose links [version/status authority](session-format-status.md); retain numbers for version-specific contracts, examples, or evidence.
 - **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
 - **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
 - **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
@@ -54,7 +54,7 @@ When the gate goes red:
 2. **Condense** content that belongs here but can be shorter.
 3. **Raise** the ceiling only when the words need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.
 
-Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root `AGENTS.md` ≤ 1,950; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 675 and this file ≤ 1,320; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `defensive-patterns.md` 550, `testing.md` 1,150, `examples/AGENTS.md` 310. Review governs unbudgeted tiers.
+Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root `AGENTS.md` ≤ 1,950; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 750 and this file ≤ 1,320; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `defensive-patterns.md` 550, `testing.md` 1,300, `examples/AGENTS.md` 310. Review governs unbudgeted tiers.
 
 ## The slop checklist
 
@@ -72,4 +72,4 @@ Hunt these in any doc; [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) runs this l
 
 ## Cross-reference with machine-checkable links, never free prose
 
-Link repository references with relative Markdown paths, never bare filenames or Agent Note numbers. `verify-md-links` rejects missing targets and dead `#fragment` anchors ([rationale](../.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md)).
+Link repository references with relative Markdown paths, never bare filenames or Agent Note numbers. `verify-md-links` rejects missing targets and dead `#fragment` anchors.

package/kb/extra/cookbook/adding-a-remote-api.md

@@ -0,0 +1,197 @@
+# Cookbook: adding a Remote API
+
+English | [中文](adding-a-remote-api.zh.md)
+
+Adding or changing a `ctx.remote` endpoint takes the five steps on this page: declare the method, declare its failures, register it on the package, consume it on the Client, and test it. Decorator semantics, lookup resolution, the generation pipeline, and the `/api` route are the mechanism and belong to the [API Gateway reference](../api-gateway.md); this page gives the action for each step and the conventions it must satisfy. Why the programming interface looks like this is in the [Typert Remote method calls Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md), and why a failure is one `RemoteError` plus a code table is in the [failure vocabulary Agent Note](../../.agents/notes/implemented/architecture/2026-08-28-ctx-remote-failure-vocabulary.md).
+
+## 1. Declare the API
+
+The owner is a Host-side Cordis service: extend `TypertRemoteService` so the service key and the wire namespace are bound together, then mark the exposed methods with `@Remote`. Mark the business method itself when its signature already satisfies the wire conventions; write a `remoteExport*` adapter only when the shape has to change (adding `signal`, reordering parameters, exporting another name), and let that adapter call the unrenamed business method. Lookup objects (`Agent`, `Session`) may only occupy top-level parameter positions, and a method that supports cooperative cancellation takes `signal: AbortSignal` as its final parameter.
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
+
+/** One stored note as a Client reads it. */
+export interface NoteRow {
+  readonly noteId: string
+  readonly title: string
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    notesController: NotesController
+  }
+}
+
+export class NotesController extends TypertRemoteService {
+  constructor(ctx: Context) {
+    super(ctx, 'notesController', { namespace: 'notes' })
+  }
+
+  /**
+   * @param agent - lookup parameter the Gateway resolves from its wire identity.
+   * @param signal - carrier cancellation, always the final parameter.
+   * @returns the notes this Agent's session owns.
+   */
+  @Remote('list')
+  async remoteExportList(agent: Agent, signal: AbortSignal): Promise<NoteRow[]> {
+    return await this.list(agent, signal)
+  }
+
+  /** The in-process API the adapter above delegates to, unchanged by it. */
+  async list(agent: Agent, signal: AbortSignal): Promise<NoteRow[]> {
+    signal.throwIfAborted()
+    return await Promise.resolve([{ noteId: `${agent.id}-1`, title: 'draft' }])
+  }
+}
+```
+
+## 2. Declare the failures
+
+A Remote failure is one class, `RemoteError`: merge the domain codes into `RemoteErrorDetailsMap` through declaration merging and `throw new RemoteError(code, message, details)` at the failure point. Do not build a family of domain error classes, and do not write an exit-mapping function; an exception unrelated to this endpoint is not pre-classified, because the Gateway folds it into `gateway/internal`. Write a `catch` only to classify an arbitrary provider exception as one domain code, and attach the original exception as `cause`.
+
+A code reads `<domain>/<reason>`, and its declaration has four placement rules:
+
+- One producer only: declare it in the producing package, next to the throw.
+- Several packages produce it: declare it in the lowest domain package both depend on (`session/not-found` in `core/session`, `workspace/not-found` in `dsh-workspace`).
+- The carrier codes `gateway/bad-request`, `gateway/cancelled`, and `gateway/internal` are declared in protocol, and the Gateway infrastructure codes in gateway — use them, never copy them.
+- A local failure that never crosses the wire stays out of the code table; express it with the caller's own type.
+
+```ts
+import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
+
+declare module '@deepseek-ai/dsh-typert-protocol' {
+  interface RemoteErrorDetailsMap {
+    /** No stored note carries that id. */
+    'note/not-found': { readonly noteId: string }
+    /** The store refused an otherwise valid write. */
+    'note/rejected': { readonly noteId: string }
+  }
+}
+
+declare const stored: ReadonlyMap<string, string>
+declare function persist(noteId: string, title: string): Promise<void>
+
+export async function rename(noteId: string, title: string): Promise<void> {
+  if (!stored.has(noteId)) {
+    throw new RemoteError('note/not-found', `no note "${noteId}"`, { noteId })
+  }
+  try {
+    await persist(noteId, title)
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new RemoteError('note/rejected', message, { noteId }, { cause: error })
+  }
+}
+```
+
+## 3. Register it on the package
+
+`@Remote` must live in a Loader entry plugin package; when the owner is an abstract seam, the controller goes in the matching package under `packages/api/`. The manifest gains the two generated entries and the protocol peer dependency, while on the Client side the `@deepseek-ai/dsh-api-remotes` assembly mounts the contribution and re-exports the type vocabulary that consumers need. Which generated artifact each entry points at, and how the generation pipeline is ordered, are in the [API Gateway reference](../api-gateway.md).
+
+```json
+{
+  "exports": {
+    "./typert": { "types": "./lib/typert.host.d.ts", "default": "./lib/typert.host.js" },
+    "./remote": { "types": "./lib/typert.remote-client.d.ts", "default": "./lib/typert.remote-client.js" }
+  },
+  "peerDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:^" },
+  "devDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:^" }
+}
+```
+
+Rerun `pnpm run build:lib` after changing a signature, the code table, the namespace, or an export name, because that is what hands the Client its new declarations and codecs; changing only an implementation body needs no regeneration.
+
+## 4. Consume it on the Client
+
+The calling plugin declares both `remote` and `remote.<namespace>` in its `inject`, and the call site writes `ctx.remote.<namespace>.<method>(...)` directly: no `Pick<ClientRemote, …>` narrowing, no hand-written method signature, no wire relay object. The result is a `RemoteResult<T>`, so branch on `if (!result.ok)` in place and discriminate by `code` rather than `instanceof` — a code branch narrows `details` on its own. An exception-flow site writes `throw result.error` (it is a real Error); whoever catches it uses `isRemoteFailure` to tell a Remote failure from a local defect and rethrows the defect. Do not write a defensive catch: a Remote call does not reject, and an assembly mistake should crash.
+
+Fixed Host facts come from `ctx.remote.$host`: `home` and `isLoopback` are plain reads with no subscription and no generation counter, and `home` is `undefined` until the first ready frame. Refresh after a reconnect through `ctx.on('connection/reset')` or a domain's own remote event. When the caller aborts a unary call, the outcome is `gateway/cancelled` on the error branch rather than a throw.
+
+```ts ignore-check
+import type { Context } from '@deepseek-ai/cordis'
+import { isRemoteFailure } from '@deepseek-ai/dsh-api-gateway/client'
+import type {} from '@deepseek-ai/dsh-api-remotes/client'
+
+export const inject = ['remote', 'remote.notes']
+
+declare const ctx: Context
+
+/** Store-side read: the error branch is handled where the code is meaningful. */
+export async function noteTitles(): Promise<readonly string[]> {
+  const result = await ctx.remote.notes.list()
+  if (!result.ok) {
+    if (result.error.code === 'note/not-found') return []
+    throw result.error
+  }
+  return result.value.map(row => row.title)
+}
+
+/** Action-side: a Remote failure becomes copy; a local fault keeps crashing. */
+export async function renderTitles(): Promise<string> {
+  try {
+    return (await noteTitles()).join(', ')
+  } catch (error: unknown) {
+    if (!isRemoteFailure(error)) throw error
+    return `unavailable (${error.code})`
+  }
+}
+
+/** Fixed Host facts as plain reads. */
+export function hostLabel(): string {
+  const { home, isLoopback } = ctx.remote.$host
+  return home ?? (isLoopback ? 'local host' : 'remote host')
+}
+```
+
+## 5. Test it
+
+On the owner side, assert the code that was thrown: recover the failure with `remoteErrorOf` after catching, then compare `code` and the details fields you care about with `toMatchObject` — never deep-compare the error object with `toEqual`, and never assert `instanceof`.
+
+```ts
+import { remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol'
+import { expect, it } from 'vitest'
+
+declare function rename(noteId: string, title: string): Promise<void>
+
+it('refuses an unknown note before writing', async () => {
+  const failure = await rename('n-404', 'fresh title').catch((error: unknown) => error)
+
+  expect(remoteErrorOf(failure)).toMatchObject({
+    code: 'note/not-found',
+    details: { noteId: 'n-404' },
+  })
+})
+```
+
+A Client-side double returns real instances: take the `RemoteError` and `TestRemote` value imports from `@deepseek-ai/dsh-client-test-runtime`, because a value import from the `api-remotes` facade would load the unbuilt assembly chain. `TestRemote.$host` is a plain field a spec assigns directly.
+
+```ts ignore-check
+import { Context } from '@deepseek-ai/cordis'
+import { RemoteError, TestRemote } from '@deepseek-ai/dsh-client-test-runtime'
+import { expect, it } from 'vitest'
+
+it('renders the failure code the Host reported', async () => {
+  const ctx = new Context()
+  const remote = new TestRemote(ctx, {
+    notes: {
+      list: () => Promise.resolve({
+        ok: false as const,
+        error: new RemoteError('note/not-found', 'no note "n-404"', { noteId: 'n-404' }),
+      }),
+    },
+  })
+  remote.$host = { home: '/home/fixture', isLoopback: true }
+
+  await expect(ctx.remote.notes.list()).resolves.toMatchObject({ error: { code: 'note/not-found' } })
+})
+```
+
+## Verify
+
+1. `pnpm run build:lib`: mandatory once a signature, the code table, the namespace, or an export name changed, because it produces the Client declarations and codecs.
+2. `pnpm run typecheck`: both the Host and the Client program, where a code merged into an unreachable package turns red.
+3. Run both sides' specs by name: `npx vitest run <owner spec> <client spec>`.
+4. Add a recorded-session snapshot when the endpoint reaches a product-visible surface, per the [testing policy](../testing.md).