create-windy 0.8.3 → 0.9.1

package/template/docs/architecture/agent-admin-workbench-plan.md

@@ -0,0 +1,41 @@
+# Agent 工具目录与调试工作台方案
+
+日期：2026-10-07。状态：源码实现已合入 main，0.8.3 已按用户授权跳过 gate 直接发布，见[发布记录](../operations/create-windy-0.8.3-release.md)；下游升级与部署待独立验收。
+
+## 业务场景与验收边界
+
+平台管理员需要确认已安装模块提供哪些工具、当前账号为何能或不能调用；业务支持人员需要在当前权限和材料范围内创建测试会话，定位模型调用、工具调用、审批和 Workflow 的失败；审计人员需要回放业务会话已有的调用事实。
+
+工具目录可查看不代表可执行。测试会话使用正常治理链；历史回放只读取已记录事实，不重新调用模型、工具或业务写入，不增加模型用量，也不计算节省时间。旧记录关联不足时标记缺失，不根据消息猜测执行经过。矛盾分析和聊天记录分析由利剑业务 owner 完成合入，本次保留业务实现，通过公开平台契约对接。
+
+## 复用与结构
+
+- 动态目录由已安装 Module Manifest、GovernedToolRegistry 和已注册 Operation Handler 生成，包含 Schema、Guard、数据分类、审批、幂等、预算、执行方式和允许的 Operation；不维护利剑专属工具列表。
+- `/admin/system/agent-tools` 展示目录；`/admin/system/agent-debug` 在一个工作台中创建测试 Session/Run、接收 SSE、展示受控结果，以及选择并逐步回放已有会话。
+- 测试 Session 必须由 PostgreSQL AH-1 Session 服务创建，随后通过普通 Run API 提交。无持久 Session 能力时明确拒绝，不降级到虚构会话。
+- 回放复用 AH-1 append-only 日志与 lineage/checkpoint，以及 `registerAgentSessionProviders()` 返回的业务消息。业务 Provider 可提供可选 Run/Workflow 引用，平台逐个按当前账号和 Scope 重新授权读取。
+- Workflow 通过公开查询接口提供全部节点尝试、分支、失败、重试和产物引用。事件只提供白名单摘要；不暴露密钥、原始推理链、Provider body 或私有 Locator。
+- internal Operation 不通过浏览器 Run 入口或历史结果读取；Workflow 专属 Operation 不通过普通调试启动。目录资格不会签发 ExecutionGrant 或代替审批。
+
+## Manifest 与接口
+
+能力基础 Key 为 `system.agent-tools`（read）和 `system.agent-debug`（read/manage）。菜单、路由、API、Feature 与审计动作在 system.agent 模块内统一登记。业务 Operation/Session/Workflow 自身权限仍要逐项通过。
+
+| 接口                                                 | 行为                             |
+| ---------------------------------------------------- | -------------------------------- |
+| GET `/api/agent/admin/tools`                         | 当前工具契约与安全拒绝原因       |
+| GET `/api/agent/admin/operations`                    | 当前 Operation 及调试启动资格    |
+| GET `/api/agent/admin/session-recordings`            | 授权 Harness 或业务会话列表      |
+| GET `/api/agent/admin/session-recordings/:sessionId` | 只读、受控、标明关联完整性的记录 |
+| POST `/api/agent/admin/test-sessions`                | 持久测试 Session 创建            |
+| 普通 `/api/agent/runs`、events、result、cancel       | 真实测试执行治理链               |
+
+## 实施与验证
+
+按目录、会话关联投影、工作台 UI 三个独立工作流实现，主 Agent 集成 Manifest、分发文件、文档与集中验证。验证包括动态模块增删、Guard 拒绝、internal 隔离、只读零执行、断线事件顺序、关联缺失、节点重试历史、未保存输入与取消。禁止用静态检查冒充测试或部署验收；不使用 Playwright、Chrome 或 GitHub Actions 自测。
+
+最终技术实现文档记录实际接口、业务 Provider 接入、升级分发、运行限制与检查证据。0.8.3 已发布并通知下游升级 owner，不代表下游已完成升级。
+
+## 参考与取舍
+
+采用已存在的 Windy [Harness](./agent-harness.md) 和 [AH-1 Session](../adr/0003-agent-session-event-source.md)，保留平台治理与业务 Provider 边界。[DeepSeek Harness 架构](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md) 的持久事件与投影分离可用于理解回放：只重建已落盘事实，实时临时输出不能替代持久结算记录。本次不迁移其插件框架。

package/template/docs/architecture/agent-harness.md

@@ -1,5 +1,7 @@
 # Windy Agent Harness：移除 ADK 与可插拔演进方案
 
+> 2026-10-29：执行层现由[内置DSH](./embedded-dsh-integration.md)接管。下文涉及Python Direct Engine、旧安装/存储及OTEL配置的内容属于历史实现；当前启动、配置与限制以[迁移运维](../operations/dsh-agent-migration.md)为准。canonical API、业务长期Session和治理契约继续有效。
+
 状态：AH-0 仓库实现完成，候选集中验证与发布证据待执行
 
 更新时间：2026-08-27

package/template/docs/architecture/agent-runtime-compatibility.md

@@ -1,5 +1,7 @@
 # Remote Agent Runtime 兼容契约
 
+> 2026-10-29：执行层现由[内置DSH](./embedded-dsh-integration.md)接管。下文涉及Python Direct Engine、旧安装/存储及OTEL配置的内容属于历史实现；当前启动、配置与限制以[迁移运维](../operations/dsh-agent-migration.md)为准。canonical API、业务长期Session和治理契约继续有效。
+
 更新时间：2026-09-02。
 
 状态：WAI-1 V1 兼容协商基础已实现。它不开放新的业务 Run 入口，也不代表外部业务系统已经可以

package/template/docs/architecture/embedded-dsh-integration.md

@@ -0,0 +1,44 @@
+# Windy 内置 DSH Agent 平台
+
+2026-10-29。参考 sharp-sword `d8e1b68219a448d5c470f6ff298fd7114db40c5c`，在 Windy `1ad816a89455b8b4c3ce37f1e3732759fafa8f48` 上提取。验收证据另见[迁移操作与验证](../operations/dsh-agent-migration.md)。
+
+## 使用者与结果
+
+业务用户通过独立同源 `/agent` 使用会话、文件、文档工具和技能；管理员在 Windy Admin 查看工具契约、调试/回放、技能版本、Workflow 预设和运行事实。可用性取决于当前登录、License、Feature、RBAC、数据范围、模型容量及 Linux 隔离。工具目录或技能可见不代表拥有执行权限。
+
+## 实现与职责
+
+Agent Server 是 Node 24.7+ 与 TypeScript workspace，固定官方 DSH `0.2.1-rc.2` 和 Cordis `4.0.5`。Bun 管理依赖及构建；DSH 原生插件安装器需要的 pnpm 随同镜像交付。通过公开 AgentLoop、Skill Provider、MCP、生命周期及 UI slot 接入，没有自维护的 DSH 内核。
+
+| 所有者         | 职责                                                                                                      |
+| -------------- | --------------------------------------------------------------------------------------------------------- |
+| Windy Server   | 当前登录、Feature/License/RBAC、数据范围、Tool Host、审批、Artifact、长期业务 Session、审计及共享技能版本 |
+| Agent 协调器   | canonical HTTP/SSE、Provider 治理、容量、SQLite、凭据保管、用户进程及受控模型/MCP边界                     |
+| DSH 与通用插件 | 原生会话、工作区、模型工具循环、压缩、文件/命令、中文、品牌、呈现、技能和有界子任务                       |
+| 项目组合       | 领域指令、领域技能、业务范围和业务呈现；调用公开平台服务，不复制平台执行器                                |
+
+`/api/agent/runs` 的创建、状态、结果、取消、幂等与 SSE 语义保留；Client Agent Session 模型协议也保留。canonical Operation 的结构化输出继续经过 Schema 校验。Execution Grant、逐次工具授权、审批、出网 DLP、内部结果加密、图片和 Context prepare/commit 由 Host 接缝执行。
+
+## 两种会话事实
+
+DSH 原生 Session 管理交互历史、文件上下文和子任务。它不替代 ADR 0003 定义的长期业务 Session，也不自动成为业务 Memory 或正式事实。业务 Workflow 的审批、不可变 Release、幂等副作用与恢复继续由现有服务持有。无需为每个 DSH 内部步骤额外创建 Windy Run。
+
+## 入口、身份和隔离
+
+`/agent` 与 `/agent/` 都由 Web 代理到产品 Server，再到 Agent Server。原生 HTML 固定相对资源基址；HTTP 与 WS 均验证来源。浏览器指定的内部身份头与转发来源不能进入可信边界。Vue 登录完成后以文档导航进入原生入口，管理面仍单独验证 `system.admin.access`。
+
+`system.agent-workbench.use` 控制原生工作台；当前产品登录在每次模型/MCP边界和连接周期重新校验。同一账号的活动 Worker 绑定已有登录及公开来源，新登录冲突返回409。登出或确认撤权回收进程、连接和模型请求；暂时无法核实授权时拒绝传输，不冒充已经登出。
+
+Linux 协调器仅为 UID/GID 切换和进程管理使用必要能力，用户 Worker 独立 UID 与0700 HOME。默认子进程通过官方扩展点继承 Landlock 文件约束和 seccomp 网络约束；隔离能力不足时拒绝执行。Provider Key、产品 Session 和内部服务 Token 不进入 Worker。共享技能附件由协调器在账号隔离目录中只读物化。
+
+用户安装的插件是该用户授权的可信代码，可访问自己的 HOME 和网络，不受默认终端子进程沙箱等同约束。个人扩展默认开放；关闭管理入口不等于停用已有插件，撤销方式见运维文档。
+
+## 容量、文件和限制
+
+原生模型请求共享 canonical 容量，并至少为既有调用链预留一个槽位。全局容量为1时原生模型任务不可用；不得根据硬件名称自动提高容量。子任务深度1、活动上限2，共享家族预算，父取消同时停止排队和子任务。
+
+默认工作区软配额512MiB、用户Worker最多2个；限制及容器资源以Compose和运行配置为准，不是并发人数承诺。当前协调器仅支持单副本SQLite，不承诺跨副本容量或HA。
+
+Office文档工具随同一镜像离线交付。DOCX预览使用固定LibreOffice WASM转PDF；Python只用于文档工具。转换、输出、缓存与期限有界，原生下载继续经过当前用户边界。复杂排版、客户模型质量和现场吞吐须独立验收。
+
+扩展方式见[DSH插件与项目接入](../development/dsh-plugins.md)，技能治理见[Agent技能](../platform/agent-skills.md)。

package/template/docs/development/dsh-plugins.md

@@ -0,0 +1,55 @@
+# DSH 插件与项目接入
+
+运行基线固定为官方DSH `0.2.1-rc.2`、Cordis `4.0.5`和Node 24.7+。不要把本次回迁同时当作上游升级。官方依赖通过Bun与锁文件安装；不修改node_modules或复制上游内核。
+
+## 项目扩展
+
+`apps/agent-server/project/host.ts`是project-owned组合，类型为`DshHostConfiguration`。可声明助理文案、工作区名称、额外指令、只读技能目录和可信Host插件。项目插件配置不承载Secret或客户端自报权限；模型、MCP身份、隔离与部署约束由最后的托管配置持有。
+
+`presetId`是部署固定的会话身份，默认`windy`。接管已有原生会话时保留其原ID；Registry、handoff和子任务统一使用该值，不重写既有会话文件。名称和说明可另行修改。项目插件可用`replaces: ["session-controller"]`接管官方公开SessionController，实现业务只读历史投影；平台先停用原条目再装入Adapter，拒绝重复接管或替换模型、身份、预算等其它托管条目。
+
+项目只读资源与插件放入`project/`，通过相对Agent Server的路径引用。整个目录随镜像交付、root所有且Worker只读；个人会话与技能仍保存在各自HOME，不通过重新初始化HOME做接管。
+
+### 受控业务边界
+
+`boundaryRoutes`可声明固定GET/POST路径，模板只支持字面片段与`:id`参数，参数仅接受最多128位字母、数字、连字符或下划线；无通配符，不得覆盖`/mcp`、`/skills`或`/v1`。重复或交叠路由在启动时拒绝。业务Handler只依赖标准TypeScript的`DshBoundaryRequest`/`DshBoundaryContext`，不接触DSH私有类型、Worker或产品Session。
+
+```ts
+boundaryRoutes: [
+  {
+    key: "project.history",
+    method: "GET",
+    path: "/business-history/:id",
+    maxResponseBytes: 2 * 1024 * 1024,
+    timeoutMs: 15_000,
+    handle: (request, context) =>
+      context.fetchProduct(`/api/my-module/history/${request.parameters.id}`),
+  },
+];
+```
+
+Handler收到`method/path/parameters/searchParams/body/signal`；查询参数仍须按业务协议校验。每次`fetchProduct`先重查当前登录，再向固定产品origin的相对`/api/`路径调用，继续经过产品API既有Manifest、Feature、License、RBAC与Scope。禁止外部URL、路径穿越、内部API、客户凭据/headers/redirect参数；HTTP方法必须与声明路由一致，仅允许JSON或二进制content-type。产品响应只保留content-type与no-store，不向Worker转发Set-Cookie或其它凭据头。
+
+GET不接收正文，POST默认64KiB，可声明`maxBodyBytes`至多20MiB；回源正文遵守同一上限，响应默认2MiB、至多20MiB。整体处理默认15秒、最多30秒，包含回源授权、HTTP及响应读取；撤权、取消和超时中止后续调用。项目声明只负责接线，不授予业务权限。业务错误回执可返回原受控状态，框架错误只返回安全码；临时登录核验故障保持503，不能误报为已登出。
+
+已匹配请求的路径上限2048字符、查询上限4096字符，回源相对URL上限8192字符；Handler不接收入站headers，产品请求headers由平台固定生成。额外只读技能目录同时进入官方发现和内置技能管理列表，不能通过个人管理入口修改或删除。
+
+通过公开Cordis service/event和DSH Slot、Skill Provider、MCP、LocalSubprocessRuntime接口扩展；监听、定时器和资源使用生命周期释放。普通业务DTO只依赖平台类型，不导入DSH私有类型。Client bundle源与生成文件一同维护，更新chunk时重建主入口revision。
+
+工作台品牌读取现有`/api/platform/branding`的softwareName、logoUrl和description。中文是部署策略，不新增i18n框架。主题复用平台语义token，不在各插件重复覆盖全局颜色。
+
+开发 Compose 和生成项目默认将`WINDY_PUBLIC_BASE_URL`留空，工作台按浏览器同源Host确定来源，不能把内部API端口9747固定为Web来源。显式配置优先且必须是用户实际访问的Web origin；HTTPS反向代理或生产Client Agent Session仍须配置该基址，后者缺失时继续fail closed。
+
+`apps/server/src/app/agent-workflow-presets.ts`是project-owned的预设注册入口。注册项必须引用已安装模块、已声明Feature/Permission和有效Workflow定义；可提供安全的同源业务入口及readiness。后台只读展示目录，正式启动仍由业务入口取得当前授权、不可变Release和材料。
+
+## 个人扩展
+
+个人插件及技能管理默认开放，按用户持久化。个人插件是该账号信任的代码；DSH官方安装器需要pnpm语义，镜像中提供固定安装器，项目包管理仍使用Bun。受部署固定的模型和身份不能通过个人profile替换。
+
+`AGENT_DSH_USER_EXTENSIONS=0`关闭管理入口及个人技能发现，但不卸载、停用已保存插件。撤销插件应先通过原生管理界面停用/卸载，再重新创建该用户Worker；保护工作区、会话和必要文件。
+
+## 验证与升级
+
+新增能力先补成功、拒绝、声明漂移和清理测试。合并候选集中执行`bun run test:merge`；Node运行时检查由`test:agent`承载。Linux协调器与沙箱检查分别使用Agent Server的`test:coordinator`和`test:confinement`。
+
+上游升级必须同批更新直接依赖和Cordis，检查公开API、最终profile合成、原生依赖完整性、UI slots、授权、取消、Office预览与隔离。依赖版本与SHA来源必须可追溯，不能仅手工改锁文件字符串。验证缺口写入交付文档。

package/template/docs/operations/dsh-agent-migration.md

@@ -0,0 +1,98 @@
+# DSH Agent 回迁、部署与验收
+
+2026-10-29。开发分支 `rayjason/dsh-agent-platform-migration`。本次交付源码、生成升级支持及本地验证；不发布npm、不推送镜像、不部署生产。
+
+## 切换与回退
+
+1. 固定当前应用SHA、镜像digest、环境配置与Agent专用volume备份。确认没有正在执行的Agent任务，停止旧Agent服务。
+2. 按新源码统一构建Agent Server、Server和Web。Node工作台代理、后台API与引擎需要同批更新，不能只替换Agent镜像。
+3. 运行正式前向数据库迁移；新增DSH技能版本/幂等回执和诊断索引。既有业务库、上传文件、长期业务Session和Workflow记录保留。
+4. 使用新的`AGENT_RUNTIME_DATABASE_PATH`，默认`/app/data/agent/embedded-dsh.sqlite`。原生HOME默认`/app/data/agent/dsh`。不读取、不迁移旧Python Run Store；旧历史详情无法回读时明确显示“运行详情不可用”，说明范围、过期或旧Agent数据重置等可能原因，统一404避免泄露记录存在性，不自动重新执行。
+5. 验证就绪、当前登录、权限拒绝、canonical调用、原生入口、撤权及文件成果。验收后再按备份策略人工清理旧Agent专用文件，禁止清理业务PostgreSQL或共享文件存储。
+6. 回退时停止新Agent，恢复同一批旧镜像及其专用备份。追加的数据库表可保留，不回写已发布迁移或回滚业务数据。
+
+升级器按文件所有权处理：未修改的旧受管Python文件可删除；客户修改的受管文件报冲突；`apps/agent-server/project/host.ts`等项目扩展保留。DSH接线涉及项目拥有的路由和组合文件时只接受已知默认基线或已经完成的目标内容，修改过的文件需人工整合，不能静默覆盖。
+
+## 配置与资源
+
+- Node要求24.7+；Linux内核必须满足Landlock完整约束及seccomp。协调器使用root切换UID，容器drop ALL后仅补SETUID、SETGID、CHOWN、DAC_OVERRIDE、KILL，启用no-new-privileges。
+- `AGENT_SERVER_INTERNAL_TOKEN`是内部服务认证；Provider继续使用`QWEN_API_URL/QWEN_API_KEY/QWEN_MODEL`。HTTPS Provider域名须在`AI_PROVIDER_HTTPS_HOST_ALLOWLIST`，内部结果加密使用`AGENT_INTERNAL_OUTPUT_ENCRYPTION_SECRET`。不向用户进程下发这些真实凭据。
+- 全局模型容量由`AI_PROVIDER_MAX_CONCURRENT_RUNS`控制。Compose保留1槽、0队列默认值；因此原生模型任务显示容量预留不可用。现场确认模型和内存后才能提高上限；原生请求始终保留至少1槽给既有调用链。
+- 原生任务上限`AGENT_DSH_MAX_ACTIVE_RUNS=2`，用户Worker默认2，工作区软配额512MiB，容器4GiB/2CPU/512PID。软配额不代替磁盘硬配额，WASM峰值RSS也不等于V8 heap限制。
+- `AI_PROVIDER_CONTEXT_TOKENS`只能填现场确认的模型serving容量；未配置时不能用DSH界面估计当作容量证明。
+- `WINDY_PUBLIC_BASE_URL`可固定公开来源；为空时同源HTTP入口保留浏览器Host用于局域网动态地址。HTTPS终止代理应设置正确公开基址，外部转发头不能代替部署配置。
+- `AGENT_DSH_HOME`父目录必须专用于Agent数据，启动会收紧普通文件权限。当前SQLite/容量仅支持单副本。
+
+个人扩展默认开放。`AGENT_DSH_USER_EXTENSIONS=0`关闭管理入口及个人技能发现；要撤销已安装插件，先停用或卸载，再重建该用户Worker。保留该用户工作区、技能和会话；禁止把关入口当作已撤销插件代码的证明。
+
+## 构建与检查入口
+
+```sh
+bun install --frozen-lockfile
+bun run --cwd apps/agent-server typecheck
+bun run --cwd apps/agent-server build
+bun run test:merge
+# 合成Provider + 实际平台用户查询工具：
+bun apps/server/scripts/check-dsh-platform-example.ts
+# 只运行新增三表与 Repository 契约，自动创建并删除专用 PG18 容器：
+WINDY_DSH_POSTGRES_TEST=1 bun test ./apps/server/src/agent-skills/postgres.integration.test.ts
+# Agent专用原生架构镜像构建后：
+bun run --cwd apps/agent-server test:coordinator
+bun run --cwd apps/agent-server test:confinement
+```
+
+普通小提交只执行静态检查；合并候选集中执行merge gate。Node契约检查使用真实DSH Loop与合成Provider。Linux原生镜像检查验证协调器、不同UID、MCP/WS、凭据剥离、撤权、共享技能与文件约束。Office另用合成DOCX验证实际转换及产物回读。
+
+正式发布才运行完整`release:verify`，本次不运行完整发布矩阵或GitHub Actions，不使用Playwright/Chrome。
+
+## 验证记录
+
+### 来源与提交
+
+同步远端后从 Windy `1ad816a89455b8b4c3ce37f1e3732759fafa8f48` 创建本分支，参考 sharp-sword 远端 `d8e1b68219a448d5c470f6ff298fd7114db40c5c`。sharp-sword 原有2个本地提交及 Server/Web Dockerfile 未提交改动保留。
+
+| 提交       | 切片                                                                 |
+| ---------- | -------------------------------------------------------------------- |
+| `3771afc4` | Node/DSH 运行时、原生工作台、隔离及通用插件，退役 Python 引擎        |
+| `6c59d398` | 工作台代理与准入、共享技能治理、Workflow 预设、诊断、后台及 Manifest |
+| `b5620876` | create-windy 生成、裁剪、升级、Docker 与构建分发                     |
+| `5a536e11` | 架构决策、平台职责、插件接缝及迁移运维文档                           |
+| `d1939dc2` | Tool Schema 透传及未终止 Run 的协议状态                              |
+| `d389ecbf` | 能力目录与开发组合接线                                               |
+| `e262ad4e` | Windy 主题、加载页及打包契约                                         |
+| `a7767955` | 受治理平台用户查询示例探针                                           |
+| `f546b11d` | WS 启动校验、Admin 目录一致性、开发身份敏感权限拒绝                  |
+| `1eb71c8e` | Node 检查入口及旧运行详情不可用说明                                  |
+| `9844e08a` | 精简 Agent 项目的调度/运维共同裁剪归属                               |
+| `f83af3a5` | 真实 PostgreSQL 18 与 Linux 文档交付检查                             |
+| `54f71825` | 配额目录替换与子任务预算检查使用显式同步，消除调度假设               |
+
+### 本地验收
+
+本地证据保存在忽略目录 `.artifacts/dsh-agent-platform-migration/` 及 `.artifacts/dsh-windy-20261029/`；不把合成产物、临时数据库或完整日志作为平台源文件提交。
+
+代码候选为 `54f718258ef1d589f97bc9c9cfdc62d606ff0cf0`。本机原生 Linux ARM64 镜像：Agent `sha256:e98e7522c1962e49f906de7bda88cc93c388717a2bc3059265895d04f28936d5`；Web `sha256:08ed2a3b79bce939682af0ab6ac345c5ef696a866e1c2564018dc4b0bfa65693`。均只在本地构建，未推送。
+
+| 范围              | 实际检查与结果                                                                                                                                                                                                                                                                 |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 静态检查          | 提交钩子执行 Oxfmt、Oxlint 与根 TypeScript 检查，全部通过。它们不计为测试。                                                                                                                                                                                                    |
+| 合并候选          | `54f71825` 上最终 `bun run test:merge` 退出0：Bun 2508通过/142跳过，Web 115文件335项通过，License 15文件49项通过，Node Agent 35项通过，Document/Speech/Embedding分别79/29/19项通过；合计3054项通过、0失败。                                                                    |
+| 真实 DSH Loop     | 35项 Node 检查通过；使用合成 Provider，覆盖结构化输出、工具/审批、授权重检、幂等与唯一终态、重放/重启、取消、连续单容量 Run、Client Agent 传输及内部结果加密。                                                                                                                 |
+| 同源工作台        | 实际 HTTP/WS 双跳、裸 `/agent` 相对资源、动态 LAN 来源、伪造身份头、登录冲突、撤权、冷启动预算及连接清理均有合约检查。                                                                                                                                                         |
+| Linux ARM64       | 固定镜像实测独立 UID/HOME、跨用户文件拒绝、凭据剥离、当前 MCP 身份、共享技能只读及版本撤销、登出回收/另一用户存活；Landlock 为 full，直接/子进程/继承句柄/PTY 的文件和网络限制通过。                                                                                           |
+| 生产 Web 镜像     | Node构建和Bun生产启动通过；只读容器中用合成同容器API上游验证就绪、静态首页、原生HTTP/WS转发及伪造内部身份头剥离，不涉及浏览器。                                                                                                                                                |
+| 技能与诊断持久化  | 专用 PostgreSQL 18 容器执行0064三表迁移及真实 Repository：4项、37个断言通过，包括并发 CAS、幂等、重建连接池后的待审计恢复、停用/回滚及30天精确过期边界/有界清理。未连接业务数据库。                                                                                            |
+| 技能界面与权限    | 导入包边界、共享范围、依赖、读取与变更审计、版本冲突、停用/回滚及未保存输入保护由服务/API/组件检查覆盖；没有浏览器 E2E。                                                                                                                                                       |
+| Workflow/错误诊断 | 动态预设只读注册、当前授权与可用性说明；实际 HTTP 失败生成诊断号，只存路由模板/安全码，拒绝越权查询并审计。查询立即排除过期记录，物理清理在失败记录写入时按分钟节流、有界执行。                                                                                                |
+| 非案件示例        | 真实平台 ToolRegistry 的 `system.users.list` 经真实 DSH Loop 调用1次，合成 Provider 调用2次，canonical SSE 与结构化汇总返回授权示例用户数1。没有利剑案件依赖。                                                                                                                 |
+| 文档与下载        | Linux UID20000、无外网、只读输入下读取 `windy-office` 技能，使用镜像文档工具生成新 DOCX/XLSX 并独立回读，保留来源摘要和文本编号001；生产下载插件+真实 LocalFileSystem+HTTP 验证字节/摘要/中文文件名及匿名、跨会话、越界、软链拒绝。Session坐标和连接身份明确使用合成 fixture。 |
+| Office 预览       | 固定 WASM 将36778字节合成 DOCX 转为29653字节完整 PDF，用时2402ms，峰值RSS1527008KiB、缺失字体为空；另行回读PDF有1页且包含中文平台用户汇总。超限前拒绝、预取消、禁用后台转换均通过。                                                                                            |
+| 生成与升级        | 真实 core 与精简 Agent 项目生成、依赖安装及完整类型检查通过；Agent 另通过实际启动组合及 Compose 配置校验。安装使用 `--ignore-scripts`，不宣称客户项目运行验收。升级的精确基线/已采纳/客户修改/删除状态、旧文件退役与环境只报告键名由契约检查覆盖。                             |
+
+文档下载复现使用 `apps/agent-server/scripts/documents-delivery-check.mjs`，通过只读 bind mount 挂到镜像相同目录，以 `--user 20000:20000 --network none --read-only --cap-drop ALL` 运行；fixture目录挂为`/fixtures`。输入为查询探针的`platform-example.json`、含工具名和汇总的合成`source.docx`、两列“编号/平台用户数”及数据“001/1”的`users.xlsx`。预览检查为`scripts/office-preview-check.mjs`，同样挂载运行，读取`/fixture/source.docx`及显式`WINDY_OFFICE_TEST_CONFIG`限制。
+
+### 验收边界
+
+本次不运行完整发布矩阵、全历史数据库迁移矩阵、客户模型/业务数据、现场并发容量或浏览器 E2E；不使用 Playwright、Chrome、GitHub Actions，不执行发布或生产部署。新表轻量检查不代替发布时完整迁移验证。DOCX复杂版式与分页未验收；示例表格没有公式，不据此声称公式重算。Office单次RSS用于资源观察，不是吞吐或并发承诺。
+
+运行边界仍为单副本SQLite和Linux隔离。默认全局1槽为既有调用链预留，原生模型任务需在现场确认容量后配置。个人扩展默认开放，插件撤销必须执行前述停用/卸载与Worker重建；试验记忆方案未启用。

package/template/docs/platform/agent-production-store.md

@@ -1,82 +1,9 @@
-# Agent 生产 Store、不可变 Release 与评估追踪
+# Agent 运行存储
 
-## 目标与边界
+2026-10-29。Agent Server 已由Node/DSH接管。canonical运行、SSE事件、Provider审计与原生用户工作区使用Agent专用本地存储；默认数据库为`AGENT_RUNTIME_DATABASE_PATH=/app/data/agent/embedded-dsh.sqlite`。
 
-Agent Runtime 的 PostgreSQL Store 是多副本生产默认实现。它只保存 Run
-执行事实、加密后的调用/事件/结果、Release 快照和评估结果，不保存业务会话、消息、
-标题、案件范围或归档策略。业务事实仍由业务模块持久化。
+当前只支持单副本，不承诺旧Python PostgreSQL Store模式或跨副本容量/HA。旧`AGENT_RUN_STORE_PATH`、`AGENT_DATABASE_URL`、`AI_PROVIDER_AUDIT_STORE_PATH`不能作为新实现已启用的证据。
 
-SQLite Store 只用于单副本本地开发和确定性验证；未配置
-`AGENT_DATABASE_URL` 且配置了 `AGENT_RUN_STORE_PATH` 时才启用。生产部署不得用
-共享文件系统模拟多副本 SQLite。
+产品PostgreSQL继续保存业务长期Session/Memory/Workflow、授权、运行绑定与报表治理事实；DSH存储不替代这些职责。内部结果仍使用Host声明的加密策略，普通历史读取不泄露internal输出。
 
-## 状态与反馈闭环
-
-同一个 `Idempotency-Key` 只能对应同一请求指纹。Run 的 canonical event 使用
-`run_id + sequence` 唯一键，读取接口按 cursor 重放；终态后追加、完成和取消都是
-幂等操作。事件或输出超过上限时，Store 写入唯一的 `run.failed`，避免运行态无限
-增长。
-
-每个工作副本领取 30 秒租约，并每 10 秒续租。租约丢失会中止当前执行，保留加密
-调用快照供其他副本接管；恢复轮询使用行锁和 `skip locked` 防止重复领取。终态数据
-按 TTL 清理，运行中数据不会被 TTL 清理。
-
-## 不可变 Release 与回滚
-
-每次 Run 固定以下坐标：
-
-- Operation 与模块版本；
-- Workflow、Prompt 和模型 Route 版本；
-- Tool/输出 Schema 摘要；
-- Manifest 摘要。
-
-这些坐标生成稳定的 `releaseId`。同一 `releaseId` 只能对应同一快照，冲突时
-fail closed，不能原地修改。业务模块通过
-`ModuleAiOperationHandlerRegistration.release` 显式声明 Workflow、Prompt 和
-Route 版本；未声明时使用模块版本。
-
-回滚不是修改历史 Release，而是重新部署此前的模块/注册版本。旧 Release 仍保留，
-新 Run 会固定到回滚后的旧坐标，历史 Run、评估和审计关联不会被改写。
-
-## 评估、用量、Attempt、审计和 Trace
-
-`POST /api/agent/evaluations` 仅接受内部 Token，可按 Release、评估集 Key 和评估集
-版本幂等记录指标；同一坐标提交不同结果会拒绝。`usage.reported` 作为加密 canonical
-event 保存。Provider attempt 审计以 `runId + attempt` 唯一保存，并可通过 Run 关联
-Release、usage 和平台 Audit。
-
-平台将请求关联值哈希为 128 位 Trace ID。Agent Runtime 用它建立 OTel 父 Trace，
-Span 只包含 Run ID、Operation Key、Release ID 和终态，不写 Prompt、业务输入、
-模型输出、Tool 参数、Actor 或 Secret。配置
-`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 后启用 OTLP/HTTP 导出，认证头由
-`OTEL_EXPORTER_OTLP_HEADERS` 注入。
-
-## 运维配置
-
-生产 Agent profile 必须配置：
-
-```dotenv
-AGENT_DATABASE_URL=postgresql://...
-AGENT_RUN_ENCRYPTION_SECRET=至少32字节随机值
-AGENT_SERVER_INTERNAL_TOKEN=随机内部令牌
-```
-
-可选配置：
-
-```dotenv
-OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://collector.example/v1/traces
-OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20...
-```
-
-加密密钥缺失或不足 32 字节时 Runtime 拒绝启动。数据库迁移必须先于 Agent Server
-启动。Provider attempt 的独立审计 Store 仍按
-`AI_PROVIDER_AUDIT_RETENTION_DAYS` 执行留存；不可把它与业务日志混用。
-
-## 故障与恢复
-
-- PostgreSQL 不可用：启动 fail closed；运行中的副本停止续租，不继续产生副作用。
-- 副本退出：租约过期后由其他副本恢复加密调用，不创建新 Run。
-- OTLP 不可用：BatchSpanProcessor 按 OTel 导出策略处理，不向业务响应暴露 Collector
-  细节；Run Store 与平台 Audit 仍是业务审计事实。
-- Release 快照冲突、评估结果漂移或幂等键漂移：稳定拒绝，要求修正发布输入。
-- 超过容量、事件数或输出大小：写入或返回有界失败，不允许无界降级。
+备份时协调停止Agent写入，保存SQLite主文件及WAL一致边界和原生HOME。采用新数据路径并允许旧Agent专用数据重置；业务数据库和文件必须保留。具体切换与回退见[迁移运维](../operations/dsh-agent-migration.md)。

package/template/docs/platform/agent-runtime-observability.md

@@ -1,5 +1,7 @@
 # AI Runtime 用量与运行报表
 
+> 2026-10-29：执行层现由[内置DSH](../architecture/embedded-dsh-integration.md)接管。下文涉及Python Direct Engine、旧安装/存储及OTEL配置的内容属于历史实现；当前启动、配置与限制以[迁移运维](../operations/dsh-agent-migration.md)为准。canonical API、业务长期Session和治理契约继续有效。
+
 `system.ai-runtime` 为 `system.agent` 提供运行事实、模型用量和缓存覆盖的管理面。它读取
 canonical Agent Run 与每次 Provider Attempt 的独立报表投影，不把管理报表变成新的
 执行入口，也不以报表写入结果改写 canonical Run 终态。

package/template/docs/platform/agent-runtime.md

@@ -1,5 +1,7 @@
 # Agent Runtime 接入
 
+> 2026-10-29：执行层现由[内置DSH](../architecture/embedded-dsh-integration.md)接管。下文涉及Python Direct Engine、旧安装/存储及OTEL配置的内容属于历史实现；当前启动、配置与限制以[迁移运维](../operations/dsh-agent-migration.md)为准。canonical API、业务长期Session和治理契约继续有效。
+
 ## 当前基线
 
 Windy 的服务端 Agent Runtime 由独立 Python Agent Server 承载，生产默认 Engine 是

package/template/docs/platform/agent-skills.md

@@ -0,0 +1,25 @@
+# DSH 技能与治理
+
+技能是可审查的工作方法和文件包，不授予工具、身份或数据权限。Windy后台治理DSH `SKILL.md`/ZIP，不依赖旧Agent Code任务或脚本执行器。
+
+## 管理与运行
+
+后台支持目录、详情、全部版本、共享范围、依赖、导入发布、停用和回滚。范围包括本人、部门和租户；读写均由Host构造的当前Scope约束。平台内置“平台工具查询”提供非案件示例；启动初始化不会覆盖已治理的后续版本或停用状态。
+
+- `GET /api/agent/skills`、`/:key`、`/:key/versions`：当前可读目录、正文及历史。
+- `POST /api/agent/skills`：导入SKILL.md或ZIP并发布新版本。
+- `POST /api/agent/skills/:key/disable|rollback`：停用或发布恢复历史内容的新版本。
+- 写请求必须携带`idempotency-key`和`expectedVersion`；回滚另携带目标`version`。正文类型由共享DTO约束。
+- `GET /api/agent/workbench/skills`：仅供当前原生身份读取可执行的已发布包；不授予管理权限。
+
+Feature是`system.agent-skill`，权限是`.read`、`.manage`、`.execute`。工具依赖必须与已注册工具的Feature/Permission一致，并逐次检查当前可用性。
+
+版本、包内容和幂等回执使用Repository+Drizzle持久化。变更先形成待审计回执，关键审计成功后才向运行时公开；重复请求复用回执，摘要漂移或版本竞争返回冲突。启动恢复未完成审计，避免崩溃后把未审计版本暴露给模型。读取审计只保存种类、Key、版本或数量，不保存技能正文。
+
+## 文件包与编辑
+
+SKILL.md必须是有效UTF-8，包含唯一YAML头的name、description和非空正文。ZIP有归档大小、展开大小、文件数和单文件上限；拒绝目录穿越、重复路径、链接、特殊文件、多个技能根和不受控YAML引用。具体上限以共享校验器和界面反馈为准。
+
+导入失败保留当前输入，保存期间阻止重复提交。关闭编辑容器、切换路由与刷新前按真实编辑基线确认，成功后才清理未保存状态。
+
+原生工作台的个人技能继续保存在当前工作区`.dsh/skills`。个人导入不产生组织发布身份。平台发布技能通过DSH公开Provider提供；每次发现/读取重新授权、比较版本摘要，附件按用户只读物化，停用或回滚撤下旧目录。已经发送给模型的历史上下文不能据此追溯消除。

package/template/package.json

@@ -21,6 +21,7 @@
     "speech:pins": "bun run scripts/provision-speech-readiness.ts",
     "dev:embedding": "PLATFORM_ENABLE_AI=true EMBEDDING_SERVER_URL=http://embedding-server:8092 docker compose --profile agent --profile embedding up --build",
     "dev:search": "OPENSEARCH_URL=http://opensearch:9200 docker compose --profile search up --build",
+    "dev:gateway": "bun run --cwd apps/windy-gateway start",
     "dev:license": "bun run --cwd apps/license dev",
     "dev:license:docker": "docker compose --profile license up license",
     "dev:signing": "bun run --cwd apps/signing-service dev",
@@ -58,15 +59,15 @@
     "release:candidate": "bun run scripts/release-candidate.ts",
     "release:verify:full": "bun run scripts/release-verify.ts --full",
     "test:packages:pack": "bun run scripts/platform-package-release.ts",
-    "test:agent": "uv run --directory apps/agent-server pytest",
+    "test:agent": "bun run --cwd apps/agent-server test",
     "test:document": "uv run --directory apps/document-server pytest",
     "test:speech": "uv run --directory apps/speech-server pytest",
     "test:embedding": "uv run --directory apps/embedding-server pytest",
-    "check:agent": "uv run --directory apps/agent-server ruff check . && uv run --directory apps/agent-server ruff format --check . && uv run --directory apps/agent-server mypy",
+    "check:agent": "bun run --cwd apps/agent-server typecheck",
     "check:document": "uv run --directory apps/document-server ruff check . && uv run --directory apps/document-server ruff format --check . && uv run --directory apps/document-server mypy",
     "check:speech": "uv run --directory apps/speech-server ruff check . && uv run --directory apps/speech-server ruff format --check . && uv run --directory apps/speech-server mypy",
     "check:embedding": "uv run --directory apps/embedding-server ruff check . && uv run --directory apps/embedding-server ruff format --check . && uv run --directory apps/embedding-server mypy",
-    "typecheck": "bun run --cwd apps/web typecheck && bun run --cwd apps/server typecheck && bun run --cwd apps/license typecheck && bun run --cwd apps/signing-service typecheck && bun run --cwd packages/ai-client typecheck && bun run --cwd packages/license-sdk typecheck && bun run --cwd packages/jobs typecheck && bun run --cwd packages/server-sdk typecheck && bun run --cwd packages/storage typecheck && bun run --cwd packages/database typecheck && bun run --cwd packages/crud-generator typecheck && bun run --cwd packages/delivery typecheck && bun run --cwd packages/create-windy typecheck",
+    "typecheck": "bun run --cwd apps/web typecheck && bun run --cwd apps/server typecheck && bun run --cwd apps/license typecheck && bun run --cwd apps/signing-service typecheck && bun run --cwd packages/ai-client typecheck && bun run --cwd packages/license-sdk typecheck && bun run --cwd packages/jobs typecheck && bun run --cwd packages/server-sdk typecheck && bun run --cwd packages/storage typecheck && bun run --cwd packages/database typecheck && bun run --cwd packages/crud-generator typecheck && bun run --cwd packages/delivery typecheck && bun run --cwd packages/create-windy typecheck && bun run --cwd apps/agent-server typecheck && bun run --cwd apps/windy-gateway typecheck && bun run --cwd packages/model-gateway typecheck",
     "lint": "oxlint .",
     "format": "oxfmt",
     "check:static": "bun run lint && bun run typecheck && bun run check:agent && bun run check:document && bun run check:speech && bun run check:embedding",

package/template/packages/database/drizzle/0064_dsh_skills_diagnostics.sql

@@ -0,0 +1,42 @@
+CREATE TABLE "agent_skill_mutations" (
+	"tenant_id" varchar(64) NOT NULL,
+	"actor_id" varchar(64) NOT NULL,
+	"idempotency_key" varchar(160) NOT NULL,
+	"request_digest" varchar(71) NOT NULL,
+	"skill_key" varchar(64) NOT NULL,
+	"version" integer NOT NULL,
+	"result" jsonb NOT NULL,
+	"audit" jsonb NOT NULL,
+	"audit_committed" boolean DEFAULT false NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "agent_skill_mutations_tenant_id_actor_id_idempotency_key_pk" PRIMARY KEY("tenant_id","actor_id","idempotency_key")
+);
+--> statement-breakpoint
+CREATE TABLE "agent_skill_versions" (
+	"tenant_id" varchar(64) NOT NULL,
+	"skill_key" varchar(64) NOT NULL,
+	"version" integer NOT NULL,
+	"metadata" jsonb NOT NULL,
+	"bundle" jsonb NOT NULL,
+	"audit_committed" boolean DEFAULT false NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "agent_skill_versions_tenant_id_skill_key_version_pk" PRIMARY KEY("tenant_id","skill_key","version")
+);
+--> statement-breakpoint
+CREATE TABLE "diagnostic_events" (
+	"diagnostic_id" varchar(41) PRIMARY KEY NOT NULL,
+	"request_id" varchar(160) NOT NULL,
+	"occurred_at" timestamp with time zone NOT NULL,
+	"expires_at" timestamp with time zone NOT NULL,
+	"service" varchar(24) NOT NULL,
+	"stage" varchar(24) NOT NULL,
+	"method" varchar(16) NOT NULL,
+	"route" varchar(256) NOT NULL,
+	"status_code" integer NOT NULL,
+	"error_code" varchar(80) NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX "idx_agent_skill_audit_pending" ON "agent_skill_mutations" USING btree ("audit_committed","created_at");--> statement-breakpoint
+CREATE INDEX "idx_agent_skill_catalog" ON "agent_skill_versions" USING btree ("tenant_id","audit_committed","skill_key");--> statement-breakpoint
+CREATE INDEX "idx_diagnostic_events_expiry" ON "diagnostic_events" USING btree ("expires_at");--> statement-breakpoint
+CREATE INDEX "idx_diagnostic_events_request" ON "diagnostic_events" USING btree ("request_id");