dsh-plugin-guide 0.3.21 → 0.3.23

package/references/official-docs/docs/user/guide/schedule.zh.md

@@ -1,21 +1,79 @@
-# 安排会话内提醒
+# Schedule 提醒
 
 [English](schedule.md) | 中文
 
-此 overlay 让一个 `dsh web` 进程显式启用 Schedule 提醒，同时不改变交付的默认 Web 组合：
+## 概述
 
-```sh
-dsh web --patch apps/cli/config/examples/schedule/cordis.yml
-```
+在对话中创建提醒，再从自动化任务页面查看活动和未运行任务，并修改活动任务的名称、指令和运行时间。每日提醒遵循保存的本地时间与时区；固定速率提醒遵循经过的时间间隔。已投递的一次性任务会保留到显式删除为止。
 
-当前 overlay 支持使用正整数 `after_seconds`、绝对时间 `at` 目标，或至少 300 秒的固定速率 `every_seconds` 间隔创建提醒。模型通过 `schedule_create`、`schedule_list` 和 `schedule_delete` 管理它们；每个结果都会把交付标为 `session-local`。
+## 目录
 
-启用此 overlay 后，成功打开且存在活动提醒的 Session 会在对话 header 中显示只读目录。目录列出完整 prompt、等待中或已逾期状态、单次或精确重复周期、浏览器本地目标时间与相对时间。侧边栏还会在 grouped、flat 与 search 行当前可用的 projection 值非空时，于标题后显示不可交互的闹钟。这些界面不会创建、编辑、删除或确认提醒；cold Session 的缓存闹钟允许短暂漏显或残留。
+- [创建提醒](#create-reminders)
+- [查看和删除任务](#manage-tasks)
+- [修改活动任务](#edit-timing)
+- [时间与投递参考](#timing-and-delivery)
+- [延伸阅读](#further-exploration)
 
-浏览器会为每条提示词附加其 IANA 时区。Time-context 会告诉模型，把未明确限定时区的日期和时间解释为该请求的浏览器时区。此假设仅用于自然语言解释：`schedule_create.at` 必须是带 `Z` 或数值偏移量且严格符合 RFC 3339 的日期时间，或是带显式 `UTC` 或 IANA Area/Location 时区的 `{ date, time, time_zone }`。Schedule 不保留或推断 Session 默认时区。夏令时缺口会被拒绝，重叠时段选择第一个时刻；成功创建的记录只保留所得的 UTC 目标。
+<a id="create-reminders"></a>
+## 创建提醒
 
-每条提醒由原 Session 日志拥有。live 根 Agent 会等待到完全 idle，再在该对话中排入一个普通 follow-up 轮次。它绝不会中途引导当前工作，也不会添加独立回执或提醒卡片。关闭进程或让 Session 保持 cold 会停止内存 timer，但不会删除记录；重新打开同一个 Session 会恢复等待并交付逾期提醒。查看 cold 历史不会激活提醒，fork 也不会继承父 Session 的提醒。
+发布的 Web profile 自带宿主 Schedule 服务与自动化任务页面。在请求模型创建提醒前，先配置模型 provider。
 
-Every 提醒始终与其创建时刻对齐。如果提醒逾期，只会呈现最新一个到期发生时点，下一个目标仍保留在原固定速率序列上。同一次 idle 决策中逾期的所有不同 Every 记录会合并为一个 follow-up，每条记录各有一个发生时点；错过的间隔不会形成积压。已到期的一次性提醒会在该批次之前运行。不支持日历表达式和 Cron 表达式。
+`standard`、`cordis` 和 `ptc` preset 声明四个提醒工具与把当前时间和浏览器时区交给模型的时钟上下文，因此这些 preset 提供 `schedule_create`、`schedule_list`、`schedule_update` 和 `schedule_delete`；`minimal` preset 两者都不声明。被委派的子 agent 看不到这四个工具，因为三个 preset 的委派行已将其 deny；即使某个调用仍能到达工具，也会被拒绝。
 
-创建和实际删除操作只有在 Session persistence 确认对应事件前缀后才会确认成功。Schedule 不提供浏览器、操作系统、邮件、短信或其他外部通知。持久 dispatch 会记录 follow-up 已经入队；它不确认模型成功或用户已收到提醒。
+向模型提出创建、列出、修改或删除提醒的请求。模型使用 `schedule_create`、`schedule_list`、`schedule_update` 和 `schedule_delete`（更新原地修改一条提醒，保留其 id 与已保存的投递记录）；「自动化任务」页面的「新建」操作则为创建打开一个新会话，其 composer 已写好该请求。支持正整数秒的一次性延迟、绝对日期时间、至少一分钟的固定间隔、带 IANA 时区的每日本地时间、带 IANA 时区和 ISO 星期（周一 1 至周日 7）的每周本地时间，以及带显式 IANA 时区的五字段 cron 表达式（表达式以规范化形式保存）。
+
+例如，请求：“每天 Asia/Shanghai 时区 23:00 提醒我查看天气。”打开自动化任务页面并选择刚创建的提醒，检查频率显示的是每日规则和所需时区，而非仅一次。一次性提醒不会在投递后变成重复任务。
+
+<a id="manage-tasks"></a>
+## 查看和删除任务
+
+从侧栏打开自动化任务页面，可跨 Session 查看提醒，而不激活相应对话。按任务已存储的名称、指令或任务所属的内部 Session id 搜索，并用唯一的“全部/已开启/未运行”状态筛选行过滤。Session 行在其 Session 有至少一个活动任务、自身空闲且未归档时显示时钟标识；归档行该格留空，其实时状态只在悬浮卡片中显示。悬停任一带活动任务的 Session 行时，最多列出其中两个任务及其频率，以及设备时区下的下次运行时间与相对时长。已打开 Session 的顶部在有活动提醒时显示仅图标时钟入口：只有一个任务时直接打开其详情，否则列出该 Session 的提醒。
+
+选择任务打开“规则”，再选择“任务运行记录”加载最新的 20 条已保存记录。每条已保存记录为一行紧凑信息：时钟图标、任务保存时区下的发生时间（一次性或间隔任务则为浏览器时区），以及保存过的指令。没有保存指令的记录不会用当前指令顶替。“加载更早的记录”增加下一页。记录按保存顺序从新到旧排列，即使时钟回拨也不改变顺序；它们不描述模型执行结果。原会话入口位于详情页签条内，因此在“规则”视图滚动时都保持可见。不带修饰键的左右方向键和 Home/End 可切换已聚焦的页签；不会拦截与 Alt、Ctrl、Meta 或 Shift 的组合。刷新任务会保留当前页签。
+
+记录空态表示查询成功且没有返回已保存记录。加载中、请求失败、任务不存在和较早记录游标无效分别显示不同提示。请求失败或返回任务不存在时，使用“重试加载发送记录”；游标无效时，使用“刷新发送记录”重新加载最新一页。请求失败时，此前加载的记录可能仍会显示，并附有警告。新的最近一次投递会刷新最新一页。离开任务或视图后才到达的响应不会替换当前视图。
+
+没有已保存历史的任务只能显示已有的最近一次回执，直到新投递增加记录；后续投递不会恢复缺失历史或清除相应提示。未保存的更早记录和指令快照无法恢复，不会用当前指令代替缺失的已保存指令。仅当宿主标记更早记录不可用时，才显示更早历史提示；尚未投递的新任务显示空态，不显示该提示。
+
+活动任务参与调度；未运行任务不会再次安排投递。一次性任务在提醒持久写入对话收件箱后变为未运行；选择所有任务或未运行即可找到它。对话顶部目录和模型 `schedule_list` 仅显示活动提醒，因此从这些视图消失并不表示保留的任务已被删除。
+
+详情页签条内的关联会话入口在元数据就绪、Session 可用且未归档时打开原对话；否则入口禁用并显示原因。即使原 Session 无法打开，任务详情与删除操作仍然可用。浏览任务不会取消 Session 归档。
+
+选择删除任务并确认，可停止未来投递并将该任务从列表中移除，包括未运行任务。删除会移除该任务及其已保存的发送记录，因此该任务的已保存历史随之消失。确认删除会关闭发起删除的面板或页签，并在同一个应用级提示里报告结果——已删除，或失败（失败时任务保留、可重试）；删除不会删除原对话，也不会撤回已进入队列的消息。该行会保留到成功查询确认剩余任务为止。查询失败时可通过重试重新加载目录；错误不会被视为查询成功的空结果。
+
+<a id="edit-timing"></a>
+## 修改活动任务
+
+在自动化任务页面选择活动任务，打开“规则”，即可修改其名称、指令和运行时间。未运行任务保持只读，修改先保存在本地草稿中，直到选择“保存更改”。编辑保留任务 id、原对话、最近一次投递回执以及全部已保存的发送记录。
+
+- Daily 和 Weekly：修改“时间”和“时区”；每周规则还可切换“星期”。时钟行显示整秒，未改动的行在提交时保留已存储的毫秒值，已存储的 IANA 时区保持不变。规则改变后，按下文的夏令时规则选择首个未来时点。
+- Every：选择“每 N 小时”“每 N 分钟”或“每 N 秒”，并按行内标出的单位填写数量；该单位下的最小间隔为 1 小时、1 分钟或 60 秒，提交的间隔为整秒。新间隔从宿主接受保存的时间起算，首个目标为一个新间隔之后。时区不影响这个经过时间间隔。
+- 一次性 After/At：分别修改“日期”“时间”两行以及“时区”。初始时区取记录已存储的时区；记录未保存时区时取本设备时区，初始钟表值在该时区下仍表示同一已存储瞬时。未保存时区的一次性规则会显示一条提示，说明输入的日期时间按所选时区解释。更改时区会保留这些钟表值并改变时点。目标改变后以相同任务 id 保存为 At，不将时区保留为重复规则元数据。
+
+各行只修改本地草稿。“保存更改”会以一次更新提交名称、指令和完整规则；草稿与已存储任务不同时显示保存栏，“取消”恢复已存储的值。“重复”菜单提供每周、周一至周五、每天、每 N 小时、每 N 分钟、每 N 秒、仅一次和自定义（cron），宿主接受其中任何一项，因此一次性 After 可保存为 At。规范化后等价的规则不写入或重设目标：相同的 Every 间隔不会重新起算，未变更的一次性目标保留 After 或 At。保存期间卡片各行禁用。离开卡片不会回滚宿主已开始的写入。
+
+刷新目录会保留你已修改的字段，其余字段取自已刷新的记录，因此其他字段的并发变化不会被未保存的修改覆盖。输入无效时显示错误并阻止保存。若投递或其他编辑改变了任务，冲突会阻止覆盖该变化；请重试以修改最新规则。更新被接受后刷新目录。更新被拒绝或无法确认与目录加载错误相互区分：应使用“重试”重新加载目录，而不是重复已确认的更新。若更新本身无法确认，应在重试前检查任务。关闭详情或切换任务后才到达的响应不会替换当前视图。
+
+<a id="timing-and-delivery"></a>
+## 时间与投递参考
+
+Session 未打开时，提醒仍然保存。宿主运行期间，在提醒到期时恢复原 Session 并排入 follow-up，不中断当前工作。重启后检查存储的任务，投递逾期的一次性提醒，或每条重复任务最近错过的一次。关闭宿主后，调度停止，直到宿主再次启动。同一 Session 的到期重复任务可以共用一条消息。
+
+固定速率提醒在间隔改变前与创建时间对齐；间隔改变后与接受保存的时间对齐。每日提醒则遵循保存的本地时间与 IANA 时区。不存在的每日本地时间或日期会被跳过；重叠时间选择当天较早的一次。绝对时间请求会拒绝不存在的本地时间，并在重叠时选择较早时刻。浏览器提供其时区来解释自然语言请求；显式指定时区可以避免歧义。任务详情在频率文案里保留钟表规则保存的时区，并把每个下一目标显示为设备时区的钟点；一次性任务仅存储 UTC 时点，因此其时间戳使用浏览器时区。
+
+已保存的发送记录确认消息已持久化到对话收件箱，不表示模型完成了所请求的工作。收件箱持久化或任务写入失败时，不增加已保存记录。收件箱持久化后崩溃或任务写入失败，可能留下未记入发送记录的已投递消息，并重复投递；不保证恰好投递一次。这不是执行历史，也不是外部通知渠道。
+
+已保存的记录在追加确认时裁剪：宿主保留确认时间落在配置的 `deliveryHistoryDays` 窗口内的记录（窗口以本次追加回执的 `deliveredAt` 向前计算），且最多保留最新的 `deliveryHistoryRecords` 条。最近一次回执始终保留，发生裁剪时标记更早记录不可用。宿主将保留的历史保存在内存中，每次确认均重写完整任务行。分页限制返回的记录数，不限制保留的历史或指令字节数。
+
+不支持暂停和每次运行新建 Session。名称、指令和运行时间的修改对模型开放：`schedule_update` 原地修改提醒并保留其 id 与已保存的投递记录；自动化任务页面也可按所选任务的绑定修改。两者都不是跨会话转交工作流。仅记录在旧 Session 日志中的提醒不会自动调度；请重新创建仍需要的提醒。此前已删除的任务记录不会被重建。
+
+<a id="further-exploration"></a>
+## 延伸阅读
+
+- [Schedule 参考](../../../packages/schedule/schedule/README.zh.md) 说明精确的时间选择器、持久化与投递限制。
+- [自动化任务页面参考](../../../packages/client/ui-schedule/README.zh.md) 说明全局页面与对话顶部目录。
+
+## 开发备注
+
+无。

package/references/official-docs/docs/user/index.i18n.yaml

@@ -1,6 +1,10 @@
-# 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:
+# Bilingual-pair consistency record for index.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/index.md
-index.md: 6b7f3f2e3f5a2cc0233ee4785d5495bf6369f025
-index.zh.md: 350185cc98d1cafdac26f48dc377384884eec284
+/:
+  en: dc6b778eb6f830d6
+  zh: dc6b778eb6f830d6
+/deepseek-harness:
+  en: 3a39bd0977f30953
+  zh: f8f5b9b5006bbe01

package/references/official-docs/docs/web-styling.i18n.yaml

@@ -1,6 +1,19 @@
-# 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:
+# Bilingual-pair consistency record for web-styling.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/web-styling.md
-web-styling.md: 1be0b629d2ccf54c5a00cfc8091a01e3d4d09bfd
-web-styling.zh.md: 106880e964a399cba825e889b5e93048589d00e4
+/web-ui-style-reference:
+  en: aab8007f4e9287d7
+  zh: 158960e753f32a91
+/web-ui-style-reference/ownership:
+  en: dc8c41fbf9869179
+  zh: e45976a585cb9c86
+/web-ui-style-reference/component-rules:
+  en: 3a35065f2be9de06
+  zh: 41291bba391fb515
+/web-ui-style-reference/corner-radii-and-settings-cards:
+  en: 118972f6c2bd6ce4
+  zh: 85f8416b03e4dd8b
+/web-ui-style-reference/changing-the-system:
+  en: 71501119492a3ad4
+  zh: 87bf6c9406d0d9ed

package/references/official-docs/docs/web-styling.md

@@ -10,9 +10,10 @@ This reference defines styling ownership and component rules for browser client
 
 Global style sheets belong in `ui-theme/src/styles/`. Component styles live beside their component as CSS Modules. A component may define a local custom property when its value is part of that component's layout or presentation contract; shared colors, typography, elevation, and motion belong to the theme package.
 
+<a id="component-rules"></a>
 ## Component rules
 
-- Reuse the control before restyling one: the [ui-primitives component catalog](../packages/client/ui-primitives/README.md#component-catalog) is the only channel that crosses feature packages, and a deliberate visual difference belongs in a prop there rather than in a second copy ([decision](../.agents/notes/implemented/architecture/2026-09-05-shared-client-control-primitives.md)).
+- Reuse the control before restyling one: the [ui-primitives component catalog](../packages/client/ui-primitives/README.md#component-catalog) is the only channel that crosses feature packages, and a deliberate visual difference belongs in a prop there rather than in a second copy ([reference](../packages/client/ui-primitives/README.md)).
 - Use CSS Modules and `clsx`; do not add a component library or Tailwind.
 - Use `--dsw-alias-*` semantic tokens in feature components. Do not copy static palette values or write literal colors there.
 - Keep theme selectors out of feature component CSS. Light/dark overrides belong to the theme owner.
@@ -22,9 +23,17 @@ Global style sheets belong in `ui-theme/src/styles/`. Component styles live besi
 - Preserve keyboard focus visibility and reduced-motion behavior when adding transitions or hover-only controls.
 - Rounded corners inherit the global superellipse smoothing from ui-theme's `corner-shape.css` on supporting engines. Pair `corner-shape: round` with every full-round `border-radius` (`50%`, `100%`, or a pill radius) so circles and capsules keep circular arcs; the ui-theme corner-shape spec enforces the pairing.
 - Elevated surfaces (menus, popovers, modals, panels, floating buttons, the composer) set `border: 0` and take `box-shadow: var(--dsw-elevation-panel)`, `var(--dsw-elevation-prominent)`, or the composer's `var(--dsw-elevation-soft)` (larger blur at lower alpha): the 0.5px hairline stroke is the first shadow layer, and `--dsw-elevation-stroke-color` rebinds or suppresses it per surface or state. Never pair a `--dsw-alias-border-*` border with an lv/elevation shadow — the ui-theme elevation spec rejects the pairing; state-colored borders (warn panels) stay real borders.
+- Existing and new dropdown, context, submenu, and selection menus use `Menu` or wrap custom content in `MenuSurface`. The material is the theme-owned `--dsw-menu-surface-fill` plus `--dsw-menu-backdrop-filter`; feature and platform CSS must not override either. The ui-theme menu spec rejects unwrapped menu/listbox renderers, material overrides, and token redefinitions. The schedule-owned `TaskMenu` and `ClockPicker` retain their existing containers and material as explicit exceptions ([owner](../packages/client/ui-schedule/README.md)).
+- Modal backdrops, including settings and confirmation dialogs, retain their translucent dark mask without blur. The theme sets `--dsw-mask-blur` to `none`; Desktop-owned modal overlays also leave the parent page unfiltered.
+- Menu background filtering stays on an isolated layer so nested menus and fixed overlays retain their positioning and backdrop. On macOS, `MenuSurface` adds an opaque backing behind page content only within each menu’s bounds, allowing Chromium to blur content over native vibrancy; CSS anchors follow placement and size, and unmounting removes the backing. Overlays without this backing use `--dsw-specific-menu`, whose theme-owned macOS fill is 94% opaque to keep underlying text from bleeding through. Other elevated surfaces using that fill pair it with the same filter on their own isolated background when they contain fixed overlays.
 - Flat borders and separators that use a neutral `--dsw-alias-border-*` token draw at `0.5px` — buttons, inputs, cards, row dividers, and separators drawn as filled boxes (menu separators, the conversation header seam, markdown `hr`, vertical rails) share the hairline weight, which Chromium paints as one device pixel. Dashed affordances and state-colored borders keep 1px; spinner ring tracks keep their width through the spec's explicit allowlist. The ui-theme elevation spec rejects wider neutral solid borders.
-- Clickable artifact links (markdown anchors, prose file mentions, web source and fetch links, produced-file chips, workflow member links) color through `--dsw-alias-link` at `font-weight: 500`, with no underline at rest and a dotted 3px-offset underline on hover/focus. Compact Thinking Markdown keeps tertiary text color and a resting dotted underline ([compact presentation](../.agents/notes/implemented/bug-fix/2026-09-17-thinking-markdown.md)). Text-leading anchors also lead with the ui-primitives `LinkIcon` category glyph riding `currentColor`, which for a well-known external host is that site's own mark instead of the globe; workflow member links and image-only anchors carry no glyph, and tool-row file links keep their grey dotted affordance ([clickable-link Agent Note](../.agents/notes/implemented/feature/2026-09-04-web-clickable-link-styles.md), [known-site mark Agent Note](../.agents/notes/implemented/feature/2026-09-16-known-site-link-marks.md)).
+- Clickable artifact links (markdown anchors, prose file mentions, web source and fetch links, produced-file chips, workflow member links) color through `--dsw-alias-link` at `font-weight: 500`, with no underline at rest and a dotted 3px-offset underline on hover/focus. Compact Thinking Markdown keeps tertiary text color and a resting dotted underline ([compact presentation](../packages/client/ui-primitives/README.md#rendering-agent-output)). Text-leading anchors also lead with the ui-primitives `LinkIconMedium` category glyph riding `currentColor`, which for a well-known external host is that site's own mark instead of the globe; workflow member links and image-only anchors carry no glyph, and tool-row file links keep their grey dotted affordance.
+
+<a id="corner-radii-and-settings-cards"></a>
+## Corner radii and settings cards
+
+The [DSH unified corner-radius standard](ui-radius.md) defines the radius scale, component size mapping, circle and capsule exceptions, nested hover geometry, and settings-card fills and strokes.
 
 ## Changing the system
 
-Add or change a shared token in the owning `ui-theme` sheet, then consume its semantic alias from feature packages. Update the owning package reference when a public styling contract changes. Visual behavior follows the [testing policy](testing.md); the [styling-system Agent Note](../.agents/notes/implemented/process/2026-07-19-web-styling-system.md) records framework rationale.
+Add or change a shared token in the owning `ui-theme` sheet, then consume its semantic alias from feature packages. Update the owning package reference when a public styling contract changes. Visual behavior follows the [testing policy](testing.md); the [archived styling-system Agent Note](../.agents/notes/archived/process/2026-07-19-web-styling-system.md) records framework rationale.

package/references/official-docs/docs/web-styling.zh.md

@@ -10,9 +10,10 @@
 
 全局样式表归 `ui-theme/src/styles/` 所有。组件样式以 CSS Modules 形式放在组件旁。当某个值属于该组件的布局或呈现约定时，组件可以定义局部自定义属性；共享颜色、排版、层级和动效属于主题包。
 
+<a id="component-rules"></a>
 ## 组件规则
 
-- 重新设计控件样式之前先复用控件：[ui-primitives 组件目录](../packages/client/ui-primitives/README.zh.md#component-catalog)是唯一跨功能包的通道，有意的视觉差异应作为那里的一个 prop，而不是另起一份拷贝（[决定](../.agents/notes/implemented/architecture/2026-09-05-shared-client-control-primitives.zh.md)）。
+- 重新设计控件样式之前先复用控件：[ui-primitives 组件目录](../packages/client/ui-primitives/README.zh.md#component-catalog)是唯一跨功能包的通道，有意的视觉差异应作为那里的一个 prop，而不是另起一份拷贝（[参考](../packages/client/ui-primitives/README.zh.md)）。
 - 使用 CSS Modules 和 `clsx`；不得添加组件库或 Tailwind。
 - 功能组件使用 `--dsw-alias-*` 语义 token。不得复制静态色板值或在其中写入颜色字面量。
 - 功能组件 CSS 不得包含主题选择器。明暗主题覆盖属于主题所有方。
@@ -22,9 +23,17 @@
 - 添加过渡动画或仅悬停可见的控件时，保留清晰可见的键盘焦点和减少动态效果行为。
 - 支持的引擎上，圆角继承 ui-theme `corner-shape.css` 的全局超级椭圆平滑。每个正圆 `border-radius`（`50%`、`100%` 或胶囊半径）必须配对 `corner-shape: round`，使圆形与胶囊保持圆弧；ui-theme 的 corner-shape spec 强制这一配对。
 - 高层级表面（菜单、浮层、对话框、面板、悬浮按钮、输入框）设 `border: 0` 并使用 `box-shadow: var(--dsw-elevation-panel)`、`var(--dsw-elevation-prominent)` 或输入框专用的 `var(--dsw-elevation-soft)`（更大模糊、更低透明度）：0.5px 发丝描边是第一层投影，`--dsw-elevation-stroke-color` 可按表面或状态重绑或抑制描边。不得将 `--dsw-alias-border-*` border 与 lv/elevation 投影配对——ui-theme 的 elevation spec 会拒绝；状态色 border（warn 面板）保持真 border。
+- 存量和新增的下拉菜单、上下文菜单、子菜单及选择菜单使用 `Menu`，自定义内容用 `MenuSurface` 包裹。材质由主题的 `--dsw-menu-surface-fill` 和 `--dsw-menu-backdrop-filter` 组成；功能及平台 CSS 不得覆盖两者。ui-theme 菜单检查拒绝未使用共享容器的 menu/listbox 渲染、材质覆盖和 token 重定义。计划任务自有的 `TaskMenu` 与 `ClockPicker` 是明确例外，保留现有容器和材质（[所属包](../packages/client/ui-schedule/README.zh.md)）。
+- 设置、确认框等模态弹窗保留黑色半透明遮罩，不模糊背景。主题将 `--dsw-mask-blur` 设为 `none`；Desktop 自有模态浮层也不对父页面施加模糊。
+- 菜单背景模糊绘制在独立图层上，保证嵌套菜单和 fixed 浮层的定位及背景采样。macOS 上，`MenuSurface` 仅在各菜单范围内、页面内容后方添加实色底层，使 Chromium 能在原生透明材质上模糊页面内容；CSS 锚点跟随位置及尺寸，卸载时移除底层。没有该底层的浮层使用 `--dsw-specific-menu`，主题在 macOS 上将其设为 94% 不透明度，防止下方文字透出。其他使用该填充的浮起表面也须配套同一模糊；包含 fixed 浮层时，将两者绘制在独立背景层上。
 - 使用中性 `--dsw-alias-border-*` token 的平面边框与分割线一律 `0.5px`——按钮、输入框、卡片、行分割线，以及以填充盒绘制的分隔线（菜单分隔、对话标题栏接缝、markdown `hr`、竖向轨道线）共用发丝线粗细，Chromium 将其绘制为一个设备像素。dashed 记号与状态色 border 保持 1px；spinner 圆环经 spec 的显式豁免保留原宽度。更宽的中性 solid border 会被 ui-theme elevation spec 拒绝。
-- 可点击产物链接（Markdown 锚点、正文文件引用、网页来源与抓取链接、产物 chips、workflow 成员链接）经 `--dsw-alias-link` 着色、`font-weight: 500`，默认无下划线，hover/focus 时为 3px offset 的点状下划线。紧凑 Thinking Markdown 保持 tertiary 文字色和默认点状下划线（[紧凑展示](../.agents/notes/implemented/bug-fix/2026-09-17-thinking-markdown.zh.md)）。带文字的锚点另以 ui-primitives 的 `LinkIcon` 分类图形（随 `currentColor`）作前置；目的地是已知外部站点时改用该站点自己的标记而非地球；workflow 成员链接与只包图片的锚点不带图形，工具行文件链接保持其灰色点线示能（[可点击链接 Agent Note](../.agents/notes/implemented/feature/2026-09-04-web-clickable-link-styles.zh.md)、[已知站点标记 Agent Note](../.agents/notes/implemented/feature/2026-09-16-known-site-link-marks.zh.md)）。
+- 可点击产物链接（Markdown 锚点、正文文件引用、网页来源与抓取链接、产物 chips、workflow 成员链接）经 `--dsw-alias-link` 着色、`font-weight: 500`，默认无下划线，hover/focus 时为 3px offset 的点状下划线。紧凑 Thinking Markdown 保持 tertiary 文字色和默认点状下划线（[紧凑展示](../packages/client/ui-primitives/README.zh.md#rendering-agent-output)）。带文字的锚点另以 ui-primitives 的 `LinkIconMedium` 分类图形（随 `currentColor`）作前置；目的地是已知外部站点时改用该站点自己的标记而非地球；workflow 成员链接与只包图片的锚点不带图形，工具行文件链接保持其灰色点线示能。
+
+<a id="corner-radii-and-settings-cards"></a>
+## 圆角与设置卡片
+
+圆角尺度、组件尺寸映射、正圆与胶囊例外、嵌套 hover，以及设置卡片的底色与描边统一由 [DSH 统一圆角规范](ui-radius.zh.md)定义。
 
 ## 变更系统
 
-在所属 `ui-theme` 样式表中添加或修改共享 token，然后在功能包中使用其语义别名。公共样式约定发生变化时，更新所属包的参考文档。视觉行为遵循[测试策略](testing.zh.md)；[样式系统 Agent Note](../.agents/notes/implemented/process/2026-07-19-web-styling-system.zh.md) 记录框架依据。
+在所属 `ui-theme` 样式表中添加或修改共享 token，然后在功能包中使用其语义别名。公共样式约定发生变化时，更新所属包的参考文档。视觉行为遵循[测试策略](testing.zh.md)；[已归档的样式系统 Agent Note](../.agents/notes/archived/process/2026-07-19-web-styling-system.md) 记录框架依据。

package/references/official-docs/packages/AGENTS.md

@@ -16,11 +16,10 @@ These package-specific rules supplement the repo-wide [conventions](../AGENTS.md
 - **Apply bounds to the complete result.** Enforce byte, token, item, and time limits where the complete emitted or retained value, including wrappers and metadata, is known; test tiny and exact limits, oversized single chunks, and multibyte byte limits.
 - **Registry contributions prove disposal** through the HMR-safety test required by [testing policy](../docs/testing.md): dispose the fiber and observe removal.
 - **Specs run concurrently** in forked workers beside other gate processes. Own each acquired port, path, and child process through teardown; a spec that passes only when run alone is a defect in the spec ([execution model](../docs/testing.md#how-specs-execute)).
-- **Publish `./invariant` only for diverging observations.** Check an owned relation under the manifest name. Otherwise omit wiring and give the package-specific README reason. Empty companions and ignored reporters fail [`verify-package-invariants`](../.agents/notes/implemented/simplification/2026-08-28-omit-unneeded-invariant-companions.md).
 
 [Naming rules](../docs/cookbook/adding-a-package.md#name-the-role-that-exists):
 
-- **Package tsconfig:** extends `tsconfig.base.json` (Client: `tsconfig.base.client.json`), sets `rootDir: src` and `outDir: lib/types`, references workspace dependencies, references `runtime-diagnostics/invariants` only when the package publishes `./invariant`, and registers in one aggregate. Packages with distinct Host and Client compiler faces use `tsconfig.host.json` and `tsconfig.client.json` leaves plus a solution-only root; ordinary two-entry Client plugins do not split ([layout](../docs/development.md#typescript-project-layout)).
+- **Package tsconfig:** extends `tsconfig.base.json` (Client: `tsconfig.base.client.json`), sets `rootDir: src` and `outDir: lib/types`, references workspace dependencies, and registers in one aggregate. Packages with distinct Host and Client compiler faces use `tsconfig.host.json` and `tsconfig.client.json` leaves plus a solution-only root; ordinary two-entry Client plugins do not split ([layout](../docs/development.md#typescript-project-layout)).
 - `src/types.ts` contains only types — no runtime code.
 - Tests live at package level under `tests/`, not `src/__tests__/`.
 - Update package README and JSDoc contracts in the same commit as behavior, and verify them against code with [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md). Group READMEs declare subsystem ownership through a canonical English page link or justified [exemption](../scripts/verify-subsystem-pages.ts).

package/references/official-docs/packages/README.md

@@ -32,8 +32,9 @@ Every package lives in exactly one group; new packages join existing groups, and
 | [`api/`](api/README.md) | Remote BFF assembly and Typert RPC gateway |
 | [`typert/`](typert/README.md) | Type graph generation, artifact loading, and runtime registry |
 | [`goal/`](goal/README.md) | Same-session goal persistence and lifecycle |
-| [`schedule/`](schedule/README.md) | Session-local scheduled follow-ups |
+| [`schedule/`](schedule/README.md) | Host-owned scheduled follow-ups |
 | [`feedback/`](feedback/README.md) | Human feedback capture and command |
+| [`telemetry/`](telemetry/README.md) | Shared Cordis OTel reporting channels |
 | [`identity/`](identity/README.md) | Shared anonymous identity |
 | [`llm/`](llm/README.md) | LLM capability family: abstract service + provider adapters |
 | [`subprocess/`](subprocess/README.md) | Subprocess capability family: Service Definition + local process-tree provider |
@@ -77,10 +78,9 @@ Every package lives in exactly one group; new packages join existing groups, and
 | [`acp/`](acp/README.md) | Automation-only Agent Client Protocol server |
 | [`interaction/`](interaction/README.md) | Human-collaboration plane: approval/interaction seams, permission preset, commands, ask-user tool |
 | [`boot/`](boot/README.md) | Shared app-bin boot glue |
-| [`host/`](host/README.md) | Web-GUI host half: API gateway + HTTP route server |
+| [`host/`](host/README.md) | Web GUI host services, directory picking, application launch, plugin inventory, and product telemetry |
 | [`client/`](client/README.md) | Web-GUI browser half: shell, wire, object services, slots, `ui-*` plugins |
 | [`test-support/`](test-support/README.md) | Test infrastructure (testkits, replay, Loader smokes) |
-| [`runtime-diagnostics/`](runtime-diagnostics/README.md) | Runtime diagnostics: package-owned invariant checks and reports |
 | [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (`Branded<B>`, home/path helpers, timeout, retention) |
 
 -----
@@ -88,7 +88,7 @@ Every package lives in exactly one group; new packages join existing groups, and
 <a id="release-expectations"></a>
 ## Release expectations
 
-Most groups are product — stable API. The exceptions: `experimental/` publishes without stability or support promises, and `test-support/`, `runtime-diagnostics/`, and `util/` are support with lower compatibility expectations.
+Most groups are product — stable API. The exceptions: `experimental/` publishes without stability or support promises, and `test-support/` and `util/` are support with lower compatibility expectations.
 
 -----
 
@@ -104,7 +104,7 @@ The dependency graph is generated: [docs/module-graph.md](../docs/module-graph.m
 <a id="package-readme-contracts"></a>
 ## Package README contracts
 
-Every package README covers purpose, configuration, extension points, and [Model Experience](../docs/cookbook/adding-a-package.md#4-write-the-package-readme) unless the model-agnostic [omission allowlist](../scripts/verify-package-readme-model-experience.ts) exempts it. It also carries `## Known Limitations and Deferred Work` or uses its [allowlist](../scripts/verify-package-readme-limitations.ts). Package conventions — exports, service access, invariants, tests — live in [packages/AGENTS.md](AGENTS.md).
+Every package README covers purpose, configuration, extension points, and [Model Experience](../docs/cookbook/adding-a-package.md#4-write-the-package-readme) unless the model-agnostic [omission allowlist](../scripts/verify-package-readme-model-experience.ts) exempts it. It also carries `## Known Limitations and Deferred Work` or uses its [allowlist](../scripts/verify-package-readme-limitations.ts). Package conventions — exports, service access, tests — live in [packages/AGENTS.md](AGENTS.md).
 
 -----
 

package/references/official-docs/vendor/README.md

@@ -2,7 +2,7 @@
 
 This directory contains source-vendored copies of the Cordis framework and its foundation libraries. They are copied into this monorepo instead of being depended on via npm, so that the harness fully owns its framework layer (auditable, patchable, pinned).
 
-All vendored packages use the **`@deepseek-ai` scope** (`cordis` → `@deepseek-ai/cordis`, `@cordisjs/plugin-<x>` → `@deepseek-ai/cordis-plugin-<x>`). The manifest table records upstream versions and source commits; each package manifest carries its Harness release version and publication metadata. Repository-owned runtime dependencies use `workspace:^`, so local builds resolve the pinned workspace packages and publication substitutes release ranges. Upstream MIT `LICENSE` files are preserved in each package directory.
+All vendored packages use the **`@deepseek-ai` scope** (`cordis` → `@deepseek-ai/cordis`, `@cordisjs/plugin-<x>` → `@deepseek-ai/cordis-plugin-<x>`). The manifest table records upstream versions and source commits; each package manifest carries its Harness release version and publication metadata. References to vendored packages use `workspace:~`, so local builds resolve the workspace packages and published ranges permit patch updates within the same minor version. Upstream MIT `LICENSE` files are preserved in each package directory.
 
 This file covers the manifest, the local-modification log, and the procedure for **updating** an existing vendored package. To **add a new** one, see the cookbook guide: [docs/cookbook/adding-a-vendored-package.md](../docs/cookbook/adding-a-vendored-package.md).
 
@@ -31,7 +31,7 @@ Intentionally **not** vendored (verified unused by this set): `reggol`, `@cordis
 Keep this log exhaustive — every divergence from upstream must be listed.
 
 1. **`hmr/src/index.ts`**: removed the `./locales/en-US.yml` / `./locales/zh-CN.yml` imports, the `.i18n({...})` call on the `Config` schema, and the `src/locales/` directory. Rationale: those imports require a runtime YAML loader hook (`@cordisjs/unyaml`) that we do not vendor; the i18n texts only localize config descriptions.
-2. **All `package.json` files**: regenerated for Harness releases with scoped names, release versions, publication metadata, precise bundled-runtime and `lib/types/**/*.d.ts` / `.d.ts.map` file entries, source exports where applicable, and declaration metadata pointing at `lib/types`. Repository-owned dependencies use the workspace protocol. HMR declares `esbuild` as a direct dev dependency for its imported `BuildFailure` type, and Loader requires `node-addon-require-builtin@^0.1.4` to match published app runtimes.
+2. **All `package.json` files**: regenerated for Harness releases with scoped names, release versions, publication metadata, precise bundled-runtime and `lib/types/**/*.d.ts` / `.d.ts.map` file entries, source exports where applicable, and declaration metadata pointing at `lib/types`. References within the vendored set use `workspace:~`. HMR declares `esbuild` as a direct dev dependency for its imported `BuildFailure` type, and Loader requires `node-addon-require-builtin@^0.1.4` to match published app runtimes.
 3. **All `tsconfig.json` files**: regenerated to extend the repo-root `tsconfig.base.json`, emit TypeScript intermediates to `lib/types`, and declare project references.
 4. **Vendored TypeScript source internal specifiers**: changed local relative imports/exports from upstream's specifier shape to explicit `.ts` specifiers so TypeScript rewrites emitted JS to `.js` while declarations keep explicit, NodeNext-safe `.ts` specifiers. This includes `loader/src/config/isolate.ts` using `declare module './entry.ts'`. Type-only dependencies use `import type` or inline `type` modifiers so ESM output does not retain erased interfaces.
 5. **`schemastery/tsdown.config.ts` and `logger-console/tsdown.config.ts`**: ours, not upstream files — per-package build-shape overrides (dual ESM+CJS output; separate node/browser entries) for the repo-root tsdown build. They read the JS emitted under `lib/types` and then write the publish runtime entries under `lib/`. Like the regenerated tsconfigs, they are not part of the upstream sync surface.
@@ -54,6 +54,10 @@ Keep this log exhaustive — every divergence from upstream must be listed.
 
 21. **`cordis/src/logger.ts` exporter disposal**: each disposer retains its registration id, so removing an earlier exporter cannot delete a later console or telemetry exporter. Covered by startup collector cleanup in `packages/boot/app-boot/tests/app-boot.spec.ts` and disabled-feedback output in `packages/session/session-telemetry-otel/tests/loader-composition.e2e.ts`.
 
+22. **Volatile config across `cosmokit`, `schemastery`, `cordis`, and `loader`**: Cosmokit supplies immutable references and framework-owned commits; `deepEqual` treats two references as equal, propagates strict comparison into arrays, compares every array slot with holes treated as undefined, handles cycles conservatively, compares URLs by normalized href, and compares other opaque objects by identity in strict mode. Schemastery adds `.volatile()`, optional/default inference, placement validation without eager lazy-schema expansion (a lazy inner is validated once when built), metadata-free serialized node compatibility, serialized metadata, reference-aware simplification, unsupported volatile values reported as `ValidationError` with their path, and `.default()` accepting the raw input type `Partial<S>` because a volatile field makes the output type carry references. Loader's save path calls `simplify` with its schema receiver (`unparse.call`), an independent fix for the unbound-`this` call. Cordis exports consumer types without changing Fiber lifecycle. Loader compares raw options strictly in `Entry.update`; for a config-only change on an active fiber it calls the pure `equalExceptVolatile` function in `config/diff.ts`, which narrows the Standard Schema to Schemastery's `Schema` type (a new type-only `@deepseek-ai/schemastery` dependency of `loader`) and recursively skips fixed volatile paths using schema metadata without executing config hooks or validation. Missing or null object nodes compare using their declared defaults, including nodes without volatile descendants; schema backedges retain raw comparison. Entry passes its actual schema and preserves ordinary context and custom-update lifecycles. For a volatile-only change, `Entry._commitVolatile` re-parses the raw config through the fiber's `internal/config` hook and `resolveConfig`, compares ordinary effective values, commits references and emits the instance-local `loader/volatile-update` declared in `loader/src/index.ts`; a changed ordinary effective value falls back to the ordinary remount, and an invalid candidate is logged while the raw config stays retained for the next activation. Cosmokit provides reference enumeration and commits, and `simplify` is called with its schema receiver. The package READMEs document these additions; schema tests live in `scripts/volatile-config.spec.ts`, Loader runtime and real-file tests in `scripts/loader-volatile-update.spec.ts`, and code replacement tests in the HMR module suite.
+
+23. **`loader/src/config/entry.ts` module identity**: retains each entry's raw import result as `moduleNamespace`, before plugin export normalization. HMR matches that object to Node's cached module namespace and updates it after a successful reload. `EntryTree.import()` keeps its existing arguments and return value; `loader/README.md` documents the additive field.
+
 ## Sync procedure
 
 To update a vendored package from upstream:

package/references/official-docs/website-docs.ts

@@ -138,6 +138,14 @@ const homeAndGuide = pairedPages([
     section: { root: '入门', en: 'Guide' },
     order: 3,
   },
+  {
+    source: 'docs/user/guide/public-deployments.md',
+    route: 'guide/public-deployments.md',
+    label: { root: '公开部署', en: 'Public deployments' },
+    sidebar: { root: 'zh-guide', en: 'en-guide' },
+    section: { root: '入门', en: 'Guide' },
+    order: 4,
+  },
   {
     source: 'docs/user/guide/python-sdk.md',
     route: 'guide/python-sdk.md',
@@ -300,7 +308,6 @@ const subsystemGroups = [
   ['内核与作用域', 'Core and scopes', [
     ['core.md', '核心', 'Core'],
     ['scope.md', '作用域', 'Scopes'],
-    ['invariants.md', '运行时不变式', 'Runtime invariants'],
   ]],
   ['会话与持久化', 'Sessions and persistence', [
     ['session.md', '会话', 'Sessions'],
@@ -330,7 +337,7 @@ const subsystemGroups = [
     ['web.md', 'Web 访问', 'Web access'],
     ['skills.md', '技能', 'Skills'],
     ['workflow.md', '工作流', 'Workflows'],
-    ['subagent.md', '子代理', 'Subagents'],
+    ['subagent.md', '子智能体', 'Subagents'],
   ]],
   ['策略与交互', 'Policy and interaction', [
     ['approval.md', '审批', 'Approvals'],
@@ -440,7 +447,7 @@ const reference = [
     ['adding-a-package.md', '新增 Package', 'Adding a package'],
     ['adding-a-tool.md', '新增 Tool', 'Adding a tool'],
     ['adding-an-llm-adapter.md', '新增 LLM Adapter', 'Adding an LLM adapter'],
-    ['adding-a-settings-card.md', '新增设置卡片', 'Adding a settings card'],
+    ['adding-a-settings-card.md', '新增设置页', 'Adding a settings page'],
     ['extension-cookbook.md', '扩展模式', 'Extension patterns'],
   ] as const).map(([file, rootLabel, enLabel], order): PairedPage => ({
     source: `docs/cookbook/${file}`,

package/references/official-plugin-dev-skill.md

@@ -0,0 +1,124 @@
+# 官方自带插件开发技能（references/official-plugin-dev-skill.md）
+
+> **这是什么**：DeepSeek Harness 自带的 preset（`packages/preset/agent-preset/`）里有一整套**官方插件开发技能**，是 0.2 世代最重要的新增资料——它描述的正是"在当前 Harness 里、由 agent 自己写并安装插件"的官方流程。
+> **本文件性质**：**要点摘录 + 原文定位**（不是逐字全文；逐字全文随官方文档副本一起在 `references/official-docs/` 之外的仓库路径，需 checkout 才能读）。凡写"官方明确"的地方都能在上游文件里逐字查到。
+> **基线**：`5badb15009ae1756c3afe0ae0cef1faafc290ccc`（`dsh-v0.2.1-alpha.1`，2026-10-03）。升级宿主后若与上游冲突，以上游为准。
+> **上游路径**（在 checkout 里，如 `D:\deepseek-harness`）：`packages/preset/agent-preset/skills/`
+
+## 1. 四个技能与各自职责
+
+| 技能 | 职责 |
+|---|---|
+| `cordis-plugin-development/SKILL.md` | 主流程：设计/评审/启用/安装/配置/调试插件、bundle、页面、面板、工具、MCP 连接 |
+| `cordis-plugin-development/references/{host-plugin,ui-plugin,mcp-bundle,practices,user-actions,verification}.md` | 六份分面参考（见 §3） |
+| `cordis-plugin-development/templates/{decoration,mcp}/**` | 可直接复制的 UI 插件模板与 MCP bundle 模板（含 locale 与 icon） |
+| `cordis-composition-reference/SKILL.md` | Loader patch 方言 + 可安装插件包清单 |
+| `editing-cordis-compositions/SKILL.md` | agent preset 组合的编辑流程 |
+| `agent-experience/SKILL.md` | 面向"模型体验"的写作/设计约束 |
+
+## 2. 主流程（`cordis-plugin-development/SKILL.md` 的硬性规定）
+
+**安装方式（官方唯一推荐）**：在工作区用普通文件写 bundle，然后用 **`plugin_manager` 工具的 `install_bundle`**，`target` 传**绝对包目录**装进当前 profile。改动对该 profile 的**所有会话**生效并跨重启保留。
+
+**官方明确禁止**（原文禁止项，逐条）：
+- 不写 profile 的 `package.json`；
+- 不写 profile 的 `cordis.patch.yml`；
+- **不在 profile 目录里跑 pnpm**；
+- 不在 `$DSH_HOME` 下创建包。
+
+理由：`install_bundle` 会做这些步骤，而"profile 之外的每一次手写都需要单独审批"。另外 `plugin_manager` 的每个动作（**包括 `list_plugins` / `list_bundles`**）在没有 Full access 时也需要审批，所以**只在结果决定下一步时才调**。
+
+**"先交付能跑的插件"五步**：
+1. 先定结果与落点。未指定的可视落点＝当前 Harness Web UI；独立图片文件或 HTML **不算**完成。先实现一个小的第一版并**先装上**，再做视觉打磨。
+2. **只查这一版需要的 API**：先 `cordis_inspect_list`，再有针对性地 `cordis_inspect_query`。UI 类要查 Client 的 `Slots.listSubTree` 与目标 slot 的注册选项/props；超出静态装饰（工具策略、agent 上下文、会话派生状态、Chat 行）要先读 `references/practices.md`；涉及用户动作再读 `references/user-actions.md`。**选定 slot 与注册 API 之后才开始写代码。**
+3. 复制匹配的模板文件到一个工作区目录，或直接在工作区写包/patch/必需的 Host·Client 文件。装之前**完成 `references/host-plugin.md` 的展示清单**（本地化标题/描述、原创或有许可的图标、按需导出资源与分发校验）——Host-only 与纯配置 bundle 同样适用。然后检查 JS 语法与清单，安装。**不要先做预览 HTML、mock 壳、design 变体、截图脚本或栅格化工具**。
+4. 读安装结果：**`application` 与 `warnings` 决定改动是否生效**——不是日志、进程列表，也不是页面的 boot payload。用**免审批**的 `cordis_inspect_query` 确认新行，而不是 `list_plugins`。`application: applied` 之后，实际用一下能力，或检查实时 Client 注册。
+5. 在同一插件里修掉观察到的缺陷；请求的结果能用就收尾，报告位置、验证状态与任何展示资源例外的理由。**不要继续做投机变体、可选功能或 mock 预览。**
+
+**知识来源的优先级（官方顺序）**：
+1. **inspection**——`cordis_inspect_query` 回答精确的 Service 方法、Event 模式（`Service`/`Event`）、已挂插件的 Config JSON Schema（`Config.listConfigs`：先按 `name` 过滤分页目录，再查 `entry` id）、本 Agent 可调用的 Tool（`Tool`）、实时 Client Slots 与主题 token（`Slots`/`Theme`）。
+2. **包文档**——`Config.listConfigs` 带 `name` 找到该包的 entry，查一个 `entry` 会返回 `packageDir`；读 `<packageDir>/README.md`。bundle 包从 dsh 安装位置解析、profile 安装的 bundle 从 profile 解析，**不要**从 `$DSH_PROFILE_DIR` 猜路径。
+3. **源码**——已安装包只带构建后的 `lib/index.js` 与 `lib/types/**/*.d.ts`（含 JSDoc），**没有 `src/`**；源码 checkout 才有 `packages/<group>/<name>/src`。先看 inspection 与 README，再从具体的安装/运行失败出发做源码级诊断。
+
+**环境变量**：profile 启动的 Harness 在每次 shell 调用里都设置 `DSH_PROFILE`（profile 名）与 `DSH_PROFILE_DIR`（其目录，`node_modules` 只含 profile 安装的 bundle）；**不以 profile 启动时不设置**。Bash 读 `$DSH_PROFILE`，Windows preset 用的 PowerShell 读 `$env:DSH_PROFILE`。`dsh --profile "$DSH_PROFILE" --dump-config` 打印组合后的 profile。
+
+**Desktop 下的读取限制（官方警告）**：Desktop 里该技能目录位于 `app.asar` 内，**只有 Host 进程自己的文件读取**能打开它；shell 命令（`ls`/`cat`/`cp`/`cmp`）、glob 与搜索工具（走原生 ripgrep 进程）、`node`、pnpm **全部失败**。**永远不要就地安装或语法检查模板**——先把模板内容复制到工作区。
+
+**启用随包发布但默认关闭的插件**：行 id 与原因写在随包 patch（源码 checkout 的 `packages/bundle/*/cordis.patch.yml`）里。写一个工作区 bundle，用 patch 覆盖该行为 `disabled: false`，并把它依赖的 Host 行一起插入；源码 checkout 的 `apps/cli/config/examples/<feature>/cordis.yml` 会列出这些行。**随 dsh 发布的包从 dsh 安装位置解析，所以这种 bundle 不声明对它们的依赖。**
+
+## 3. 六份分面参考的要点
+
+### 3.1 `host-plugin.md` — bundle 与 Host 插件
+
+- 最小 Host-only bundle **不需要依赖、安装脚本或构建步骤**：
+  ```json
+  { "name": "@local/my-plugin", "version": "1.0.0", "private": true, "type": "module",
+    "exports": { ".": "./index.js" }, "dsh": { "bundle": { "patch": "./cordis.patch.yml" } } }
+  ```
+- **展示元数据与图标清单**（Plugin Manager / Settings 在**不激活**插件的前提下读取）：`locale/en.json` 里写 `meta.title`/`meta.description`，并按用户语言补 `locale/zh.json` 等；图标须原创或有再分发许可、保留署名；导出 `./locale/*.json` 与 `./icon`，并把 patch、locale、图标与**每个运行时文件**都放进 `files`。**本地目录安装链接的是 checkout，`files` 不过滤链接目录**——要直接检查文件。图标支持 SVG/PNG/JPEG/WebP，**≤ 256 KiB**，且 realpath 之后必须仍在包内（绝对路径、URL、指向包外的 symlink 都被拒）。**文件名合规不等于字节能渲染。**
+- 包根插件也可以在 `package.json` 顶层写 `icon`（优先于 `./icon`，路径相对清单目录）。**子路径插件（如 `my-plugins/search`）不是包，永远不读 `package.json`**——它导出 `./search/locale/*.json` 与 `./search/icon`。
+- Host 插件导出形态（**不要混用**）：`export function apply(ctx, config) {}` + 可选 `export const inject = ['tools']` + `export const Config`；或者一个 **service class 作为 default export**。所有资源都在 `apply` 里用 `ctx.effect`/`ctx.on` 注册并返回清理函数。声明了 `Config` 的插件会在激活时校验该行的 `config`——**写 config 之前先查 `Config.listConfigs` 拿 schema，并跟进返回文档里的 `$defs` 引用**。
+- 安装/启用/观察：`install_bundle` 负责包安装与 bundle 选择，**不要用 shell 复现**；只有用户明确批准了报告出来的 pending build 脚本后才传 `approvedBuilds`。`list_plugins`/`list_bundles` 给出精确标识符，`set_plugin`/`set_bundle` 开关，`remove_bundle` 移除。**分开看"保存状态"与"激活结果"**：`failed` 要诊断，`overridden` 表示更高优先层胜出，`restart-required` 表示**未生效**。新装 bundle 可以经 HMR 激活；**替换已安装包需要重启**才能载入新的 JS 模块代。
+
+### 3.2 `ui-plugin.md` — Web 页里的 UI 插件
+
+- 读 `templates/decoration/` 并把文件写进你的 bundle 目录：它的 `package.json` 在 bundle patch 之外加 **`dsh.client` 段**（`platform`/`immediately`/`inject`）与 **`./client` 导出**。`index.js` 导出 `export function apply() {}`；patch 插入一行，行名即包名。
+- 简单绘图优先选**已分配空间**的 slot，如 `conversation.composer.dock`；第一版就留在这个 slot 的流内，**不要**围绕宿主控件规划运动轨迹。只有需要覆盖层且落点已知时才用 `shell.overlay`。
+- 浏览器产物注册一个**懒工厂，其 id 等于包名**。React 来自浏览器模块表——**不需要**第二份 React、CDN script 或 UMD 查找。编译型源码用部署自带的 Client 构建工具产出该格式；非基线运行时 import 在 `dsh.client.external` 里声明。
+- `templates/decoration/client.js` 通过 `ctx.slots.inject` + `ctx.slots.register` 把懒工厂注册进 `conversation.composer.dock`；换 slot 时按 `Slots.listSubTree` 给出的 props/options 来写。
+- **工厂保持无副作用**：样式、定时器、监听器等资源在 `apply` 里用 `ctx.effect`/`ctx.on` 注册并返回清理函数；组件局部样式渲染成 React 元素，卸载即移除。容器与控件继承宿主主题；只有 artwork 可以用自己的配色。**可见文案走 Client locale 服务。不要替换 app root，也不要往 `document.body` 追加第二个应用。不要读别的插件的 DOM、样式表或组件源码去猜位置——选一个已经分配好空间的 slot。**
+
+### 3.3 `mcp-bundle.md` — 接一个 MCP server
+
+- 纯配置 bundle：清单只要有唯一 name、version 与 `dsh.bundle.patch`，**不需要** Host/Client 入口文件。patch 插入**已安装的** `@deepseek-ai/dsh-mcp-client`，配 `serverName`、`transport: streamable-http`、`url`、`failOnStartupError: true`。
+- 换掉 endpoint、经 `plugin_manager` 装好，然后调 `mcp__demo__ping` 之类新出现的 `mcp__<serverName>__<tool>` 验证。
+- stdio 用 `transport: stdio` + `command` + 可选 `args`/`env`/`cwd`；`Config.listConfigs` 查已装行会返回完整 client schema。**环境凭据会被清洗**：用 Loader 的 `!!js` 引用已有凭据，**不要把密钥粘进对话文本**。失败时**修同一个 bundle，不要造重复的**。
+
+### 3.4 `practices.md` — 插件实践总纲（最值得先读的一份）
+
+**六条原则**
+1. **会话日志是唯一真源**：模型看到的一切都必须能从已提交的会话事件重建；fork/resume/replay 都从日志派生。**插件内存只是派生缓存。**
+2. **注册是被 ctx 拥有的 effect**：插件卸载、agent 释放、slot 折叠、profile patch 都会撤销对应 ctx 上注册的东西。**要选对拥有者 ctx**；注册在别的 ctx 上（如 `agent.ctx`）的注册有**两个**拥有者——必须把它的 disposer 也留在自己插件的 effect 里，这样任一侧 teardown 都能移除。
+3. **框架负责驱动，插件只负责计算**：session projection、Conversation 组装、slot 渲染已经替你订阅、缓存、发布。自己去订阅/重扫/写 DOM 就是绕过这套增量机制。
+4. **扩展点是共享的：用最弱的够用机制**。由弱到强：`ctx.tools.restrict()`（只能移除工具）→ `ctx.tools.guard()`（只能拒绝）→ waterfall 监听器（可改写、依赖注册顺序）→ `system-prompt/assemble`（替换整个组装结果）。机制越强，你要替其他插件保留的东西越多。
+5. **别的插件、别的 Harness 版本会读你写的数据**：未知事件类型、更老的读方、更老的缓存状态都会遇到你写的东西——按 Harness 提供的信封字段与版本声明兼容性。
+6. **插件 UI 就是 Harness UI 的一部分**：用户看到的是一个应用，所以插件要用宿主的主题 token、locale 与布局模式，并匹配宿主组件的外观与行为。**能不能做到由"在哪渲染"决定——先选渲染面再写视图**；后面在错误的面里做样式救不回来。
+
+**稳定性（逐条可执行）**
+- 不拥有该决策的 waterfall 监听器（`agent/pre-step`、`agent/request`、`llm/stream`、`tools/pre-execute`、`tools/execute`、`tools/post-execute`）**必须返回 `next()`**。改写 `agent/pre-step` 决策时要**展开**它（`{ ...decision, messages }`），否则 `startsRequestSeries` 之类字段会丢。
+- 必须与顺序无关地成立的拒绝用 `ctx.tools.guard()`（同步）；需要 await（比如问用户）的决策从 `tools/pre-execute` 返回 `ask`。只对某个 agent 隐藏工具＝在那个 agent 的 ctx 上 `ctx.tools.restrict()`（它让 schema 展示、查找、执行保持一致）。**最终结果只看 `tools/result`**；只有要变换结果才用 `tools/post-execute`。**不要监听 `system-prompt/assemble` 来增删工具或文本。**
+- 加提示词文本用 `ctx.systemPrompt.section()`。加 per-agent 上下文用 `agent.inject()`——它在调用时记为 `agent/inbox/spliced`，进入下一次获准的 step。**`agent/request` 监听器不能改请求消息。**
+- per-agent 行为注册在 `agent.ctx` 上（在 `agent/created` 监听器里拿到），这样该 agent 释放时一起移除。**把它包在一个 `agent.ctx.effect()` 里，并且把这个 disposer 按 agent 记在自己插件的 effect 里**——卸载插件本身**不会**释放 `agent.ctx` 的注册。
+- 可选服务放进 `inject` 或 `ctx.inject([...], ...)`，这样在没有它们的 profile 里插件保持不激活，而不是抛错。
+- **绝不要用新的 `type` 追加会话事件**：读方只在事件带信封 `ignorable: true` 时接受未知类型，而运行时 `Session.append()` 写不了这个标记，于是**会话会拒绝重新打开**。插件状态从既有事件推导，或放进 inspection 找到的 storage 服务。
+- 可调值放进插件的 `Config`，让用户在 `cordis.patch.yml` 里改——**用户的 patch 层能跨升级保留**。
+
+**性能**
+- per-session 状态放进 `ctx.sessionProjections` 单元，**不要**订阅 `session/event` 再重扫 `session.events`。`apply(state, event)` 是**纯同步**的，对它忽略的事件**返回同一个引用**，所以未变状态在下游零成本；读取用 `stateOf()`。`view()` 在值未变时返回同一引用，从而抑制发布。
+- projection 状态保持**纯 JSON**，字段或 fold 语义变化时 bump `stateVersion`：投影缓存会 checkpoint 它，冷读只回放尾巴，过期 checkpoint 被丢弃。
+- **等持久事件**（`turn/end`、`assistant/message`、`tool/result`），实时 token 从 `agent/assistant-stream` 渲染。**不要轮询 `agent/status`。** `whenIdle()` **不**代表"一次 followup 结束了"——多个输入可以共享同一个运行区间。
+- 会启动工作的定时器调用 `agent.followup()`（它**唤醒** agent）；`agent.inject()` **不唤醒**，所以注入的上下文可能在 inbox 里等到别的输入才被采纳。定时器要在拥有它的 effect 里清除。
+
+**UI**
+- 插件页面渲染成 slot 里的 React 组件。**不要**从 Host 提供一个 HTML 页面再 iframe 嵌进去：iframe 文档拿不到宿主主题 token、明暗切换和 `ctx.locale`。
+- 用 `cordis_inspect_query` 的 `Theme` 列出的主题 token（`--dsw-alias-*`）做样式；字面颜色只用于 artwork。token 是最低风险的匹配方式：token 改名只会让外观退化，**永远不会弄坏渲染**。间距/字号/行模式照抄同类宿主页面（管理类列表的参照是 Plugin Manager 页）。
+- **不要** `require('@deepseek-ai/dsh-client-ui-primitives')` 或把任何 Harness Client 包当模块加载；`dsh.client.inject` 只做激活排序、保持允许即可。它们会不打招呼地变化，纯 JS 插件没有类型检查，而**抛错的组件会把你的 slot 条目整块搞白**（console 里是 `slot entry crashed in '<slot>'`）。**自己写控件并对齐宿主**：从 primitive 里把标记、CSS 与行为抄进插件（DSH 源码 checkout 的 `src/*.tsx` 与 `*.module.css`，或已安装包的 `lib/index.js` 与 `lib/**/*.css`），或在连着的页面里观察渲染出来的宿主控件。抄来的 class 要改到你自己插件的前缀下，只保留 `--dsw-alias-*` token 引用，并保留用户依赖的行为（Modal 焦点与 Escape、`role="switch"` + `aria-checked`、Tooltip 落位）。这样 token 就是唯一的共享样式依赖。
+- 只通过 slot 贡献：`ctx.slots.inject(ownerKey, () => ctx.slots.register(...))`——回调里的注册在拥有它的声明折叠时释放、恢复时重新安装。会话数据经 slot props 的 selector hook 读取，订阅**最小切片**。**不要**在组件外写 DOM，也不要往 `document.body` 追加。
+- 加 Chat 行：用 `ctx.uiConversation.events.register()` 注册事件定义，并在 `conversation.chat.node` slot 下按该定义的 `kind`（即渲染键）注册视图；分页、Turn/Step 落位与增量组装由 Conversation 层负责。
+- Client 需要会话派生值时，在 Host projection 上声明 **`wire.view`**——值算好了再送到 Client，**Client 不自己 fold 会话事件**。
+
+### 3.5 `user-actions.md` — 用户动作与 agent 工具
+
+- **一个操作，两个调用方**：① 实现成一次 Host 服务方法（返回结果或显式状态，失败带原因）；② UI 动作经 inspection 找到的 Client 可调 Host 入口（如 `ctx.remote.commands.execute()` 跑的会话命令）调用它并显示失败；③ 用参数与语义一致的 agent 工具暴露同一操作（相关操作可用一个 `action` 参数共用工具），工具调同一个方法并把结果作为工具结果返回。
+- **授权/确认类动作仅限用户**（批准工具调用、回答 agent 的提问、放宽策略）。**不要在 UI 与工具两条路径里各维护一份操作逻辑。**
+- 验证：双调用方的操作**只用工具**跑一遍，比较状态变化、返回值与失败是否与 UI 动作一致；用户专属动作要验证 agent **无法**执行或授权。
+
+### 3.6 `verification.md`
+
+无浏览器控制时的页面/面板设计核查流程（配合 §2 第 4-5 步使用）。
+
+## 4. 与本知识库的关系
+
+- 本文件是**索引与摘录**；机制细节（精确签名、事件 `@mode`、Config schema）永远以 **inspection** 与 `references/official-docs/docs/**` 为准。
+- 官方这份技能覆盖"在会话里让 agent 写并安装插件"；本知识库另外覆盖**对外发布**（npm/tarball/git 通道、`prepare` + `allowBuilds`、五语 README、质量门禁）与**版本迁移**（[migration-0.2.md](../guide/migration-0.2.md)）。
+- 上游路径随宿主版本变化（本文件基线 `5badb15009`）；`preset/agent-presets` → `preset/agent-preset` 的改名发生在 `d1e22a7e24`。

package/references/sources.md

@@ -33,12 +33,14 @@
 
 ## C. 本地 checkout 文档副本（references/official-docs/）
 
-- `docs/**`（215 个 md，含全部 `.zh.md` 双语对）— 教程/架构/子系统/API/cookbook 全量
-- 仓库根文件（**2026-08-14 晚新增**）：`AGENTS.md`、`CLAUDE.md`（上游为 symlink→AGENTS.md，副本存其目标文本）、`BENCHMARK.md`、`CONTRIBUTING.md`/`.zh.md`/`.i18n.yaml`、`README-zh.md`/`.i18n.yaml`、`THIRD_PARTY_NOTICES.md`、`LICENSE`
+- `docs/**`（**369 个 md**，含 182 个 `.zh.md` 双语对）— 教程/架构/子系统/API/cookbook/upgrade-guide/persistence-changes 全量（计数以 `references/official-docs/SNAPSHOT.md` 为准）
+- 仓库根文件（**2026-08-14 晚新增**）：`AGENTS.md`、`CLAUDE.md`（上游为 symlink→AGENTS.md，副本存其目标文本）、`BENCHMARK.md`、`CONTRIBUTING.md`/`.zh.md`/`.i18n.yaml`、`README.zh.md`/`.i18n.yaml`、`THIRD_PARTY_NOTICES.md`、`LICENSE`
 - `packages/AGENTS.md` · `packages/README.md` · `vendor/README.md`
 - `website-docs.ts`（站点投影清单）
 - 上游英文 `README.md` 不进入本目录（与 KB 索引同名），线上快照在 `downloads/github/harness/README.md`
 - 同步脚本本次加固：pathspec 全部 `:(top)` 锚定（避免 basename 全局匹配误收仓库深处 symlink）；Windows 下无法解出的 symlink 按其 blob 目标文本落地；目的目录只保留范围内条目（曾因一次失败抽取残留污染，已由脚本自动修剪 107 项）。
+- **不在站点路由表里的重要文档**（本地有副本、站上找不到）：`session-format-status.md`、`upgrade-guide/**`（6 篇，**无 index、无任何入链**）、`persistence-changes/**`、`ui-radius.md`、`web-styling.md`、`module-graph.md`、`dependency-catalog.json`、`persistence-schema.json`——清单见 [guide/links.md](../guide/links.md) §2.1。
+- **官方自带插件开发技能不在 `docs/` 下**：在 `packages/preset/agent-preset/skills/**`（本库要点摘录见 [official-plugin-dev-skill.md](official-plugin-dev-skill.md)）。
 
 ## D. 社区与生态（downloads/community/ + references/community-ecosystem.md）
 
@@ -80,10 +82,13 @@
 
 `downloads/github/harness/discussions/`（说明文件 `README.md` 含分类统计与精选清单；刷新脚本 `scripts/archive-discussions.ps1`）：
 
-- `list.json` —— 全部 **1654 条**讨论（title/body/category/answers 等，正文即文档；08-14 首版 1408 条，08-15 增量 +246）
+- `list.json` —— 全部讨论（title/body/category/answers 等，正文即文档）；**2026-10-06 刷新**：`archive-discussions.ps1` 全量重跑（list.json 约 31.6 MB）：**list=5000、精选线程 1648**（`README.md` 由脚本自动生成分类统计：General 2250、Show Your Plugins! 1148、Ideas 1031、Q&A 565、Polls 5、Announcements 1）。
+  - ⚠️ **REST 分页天花板**：`/discussions` 走 REST 只能翻到 **5000 条**（脚本 `page -le 50` × 100/页）；同期 **GraphQL** `UPDATED_AT DESC` 报告仓库 **total_count=8850**。所以归档覆盖的是前 5000 条而非全量；需要更全时按 GraphQL 补抓（社区刷新用的就是 GraphQL 分页：31 页 × 100 覆盖 `UPDATED_AT >= 2026-09-14` 的 3100 条）。
 - `comments-<n>.json` —— 精选线程的全部评论（规则：Announcements/Q&A/Ideas 评论≥1；General/Show and tell 评论≥3 且非拉群帖）
-- `_selection.tsv` —— 精选清单
-- 背景：官方仓库 **Issues 关闭、Discussions 开放**（社区反馈主渠道）；排障与功能讨论代表：#49 ArchLinux 安装、#55 pnpm 全局安装 cordis-plugin-timer 缺失、#60 外部 GUI/ACP bridge、#30 win32 目录选择器；**08-15 新编号至 1629+**，代表作 [#1629 RFC 官方插件脚手架](https://github.com/deepseek-ai/deepseek-harness/discussions/1629)（08-15T01:15Z）、安全审计类 #817/#454/#523/#250
+- `_selection.tsv` —— 精选清单（1648 行 + 表头）
+- 背景：官方仓库 **Issues 关闭、Discussions 开放**（社区反馈主渠道）；**2026-10-06 API 复核**：`has_issues=false`——**没有 issue tracker、也不收 PR**，Discussions 是唯一渠道；仓库 star≈244,304、fork≈29,266、最后 push 2026-10-03、许可 MIT。代表作 [#1629 RFC 官方插件脚手架](https://github.com/deepseek-ai/deepseek-harness/discussions/1629)、[#6520 本库的未修复问题汇总帖](https://github.com/deepseek-ai/deepseek-harness/discussions/6520)（最后活动 2026-09-23，**无维护者回复**）。
+- **重要结论（写进贡献规则）**：本轮通读的 3100 条线程里，**没有任何维护者确认过修复或设计决定**；唯一的"官方决定"权威记录是 **GitHub Releases 说明**（仓库无 CHANGELOG）。引用"官方已确认"必须落到 Release 原文或提交号。另：**Announcements 分类只有 1 条**——官方不在 Discussions 发版，发版只在 Releases。
+- **本窗口最高价值的线程**：#8199（升级后 22 个第三方 bundle 里 11 个被判不兼容 + `minimumReleaseAge` 静默阻塞）、#7850 / #8821（`plugin add` 不补齐 layer 行）、#8633（宿主插件失败在 `dsh web` 下不可见）、#8688（`connection.rpc.handle()` 405，自 0.1.0-rc.7 起）、#8862（profile 内 dsh 包遮蔽运行时）、#8968 / #8857 / #8635（运行中改 `cordis.patch.yml` 的三种破坏后果）、#8590（社区 0.1.5-rc.2 → 0.2.0-rc.2 移植实录）、#8669（12 评论真实插件构建日志，含 `inject` 写成函数导致整 bundle 被自愈禁用的血案）、#8537（插件验收 profile 隔离提案 + `sanitizeProfile` 复盘）、#8836（`assistant()` 空白文本块 → 云端 400）、#8649（桌面端 skill provider 因 `app.asar` 相对根丢光文件系统 skill）。
 
 ## G. npm 包归档（2026-08-14 晚新增）
 

package/scripts/archive-discussions.ps1

@@ -48,7 +48,12 @@ if (Test-Path (Join-Path $OutDir 'list.json')) {
 }
 $all = @()
 $page = 1
-while ($page -le 50) {
+# REST /discussions caps at 5000 rows (50 pages x 100). The cap is explicit so a
+# silent truncation cannot be mistaken for a complete archive: the run reports
+# when it stops at the ceiling, and the README records the ceiling alongside the
+# GraphQL total_count (which is larger).
+$pageCap = 50
+while ($page -le $pageCap) {
   $items = Get-Api "https://api.github.com/repos/$Repo/discussions?per_page=100&page=$page&sort=created"
   if ($items.Count -eq 0) { Write-Output "page ${page}: 空页,列表结束"; break }
   $all += $items
@@ -57,6 +62,9 @@ while ($page -le 50) {
   $page++
   Start-Sleep -Milliseconds 500
 }
+if ($all.Count -ge ($pageCap * 100)) {
+  Write-Output "WARN: 列表在第 $pageCap 页触顶(REST 5000 条上限)——归档为前 5000 条,非全量;更全的历史需按 GraphQL UPDATED_AT 分页补抓"
+}
 if ($all.Count -eq 0) { throw 'discussions 列表抓取失败(0 条)' }
 if ($prevCount -gt 0 -and $all.Count -lt [Math]::Floor($prevCount * 0.9)) {
   throw "列表疑似缩水: 上次 $prevCount 条, 本次仅 $all.Count 条 —— 拒绝覆盖归档,请检查网络/配额后重跑"