dsh-auto-flow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 方世伟
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# dsh-auto-flow
+
+A DeepSeek Harness plugin.
+
+DeepSeek Harness 插件 Bundle（Host 半 + Client 半同包），演示通信设计：
+
+- **重通道：@Remote 严格模式**（`AutoFlowService`）——Host 服务，浏览器经 `ctx.remote.autoFlow` 调用，双向 zod 校验 + 完整类型，契约由 `pnpm typert:gen` 生成（`lib/typert.*`，提交进 git）。
+- **轻执行也走 @Remote**：`exec` 方法在宿主内经 `ctx.shell`（与 bash 工具同一执行器，绝不经过模型）执行命令行，返回结构化结果（`exitCode`/`signal`/`stdout`/`stderr` 等），**输出只回调用方 UI，不进会话日志、不动界面**；shell 是可选依赖，未组合 shell 提供方时 `exec` 报错、插件其余部分照常工作。
+- **注意**：内置 `ctx.remote.commands.execute` 是**会话命令通道**——结果会生成 durable 命令节点进会话并驱动界面（斜杠命令语义），仅用于"就是要当命令用"的场景；模板不拿它演示机器执行，以免污染会话。
+- **模型工具**：`plugin_auto_flow` 复用上面的服务。
+- **持久化只进 domain storage**：问候落 domain storage（与 session 日志隔离）；不追加自定义会话事件（harness 持久化读路径会拒绝未知事件类型，且 `Session.append` 无法标记 `ignorable`）。
+
+> English TL;DR: A dsh plugin bundle demoing Host↔Client communication — strict `@Remote` RPC (`send`/`list` for heavy comms, `exec` for shell-backed lightweight execution whose output stays in the UI and never enters the session log). Run `pnpm typert:gen` to regenerate the RPC contract.
+
+## 能力清单（每项都对齐官方实现）
+
+| 能力                                | 官方参考                              | 位置                                                |
+| ----------------------------------- | ------------------------------------- | --------------------------------------------------- |
+| `@Remote` 严格模式                  | `goal`、`message-feedback`            | `src/index.ts` 的 `send`/`list`                     |
+| `@Remote exec` 宿主 shell（轻执行） | `tool-bash`（shell seam）             | `src/index.ts` 的 `exec`                            |
+| 模型工具                            | `tool-bash`、`tool-todo`              | `plugin_auto_flow`（`defineTool` + `presentCall`）     |
+| 斜杠命令                            | `commands` + `plan-mode`              | `/auto-flow`（`ctx.commands.register`）             |
+| 插件 Config + 设置 UI               | `settings` + `llm-deepseek`           | `installSection` + `settings.general.item`          |
+| 持久化（domain storage）            | `storage-domain` + `message-feedback` | `src/domain.ts`                                     |
+| 客户端 UI 槽位（slots）             | `ui-goal`、`ui-message-feedback`      | `conversation.input.dock` 等三槽位                  |
+| 多语言 locale                       | `ui-*` 的 `locales.ts`                | `src/client/locales.ts`                             |
+| 跨插件服务协作                      | Cordis `Service`                      | `dsh-auto-flow-core` 的 `autoFlowFormatter` |
+
+## 开发
+
+```sh
+pnpm install            # 安装全部工作区依赖（含 devDependencies）
+pnpm typert:gen         # 首次必跑：生成 @Remote 契约（lib/typert.*），之后改动签名时重跑
+pnpm dev                # 开发：tsdown --watch 双段（含首次构建）
+pnpm typecheck          # 三程序检查：Host + Client + 默认程序（tsconfig.json，均不 emit）
+pnpm test               # 单测：Host 半 + 浏览器半 jsdom（需先跑过 typert:gen）
+pnpm build              # 一次性构建产物（发布用）
+pnpm check              # 一键门禁：lint + typecheck + test + build（发布前跑）
+```
+
+### 热更新边界
+
+日常开发就是根目录 `pnpm dev`（`tsdown --watch` 同时 watch 两半）：
+
+| 面                                      | 更新方式                                                                         |
+| --------------------------------------- | -------------------------------------------------------------------------------- |
+| **Client 半**（`lib/client.js`）        | `dsh-client-hmr` stat-poll + SSE **热替换**（无需刷新/重启）                     |
+| **Host 半**（`lib/index.js`）           | 插件代码**需重启 dsh**（官方 Loader 启动即解析插件，代码不热更）                 |
+| **配置/patch 层**（`cordis.patch.yml`） | 官方 `watchUserPatches` **热重组**（无需重启；仅 config/patch 层，插件代码除外） |
+
+只想 watch 单面时才用 `pnpm dev:client` / `pnpm dev:host`。
+
+本地试装到 dsh：
+
+```sh
+dsh plugin --profile web add "<workspace>/packages/dsh-auto-flow"
+```
+
+## @Remote 契约维护
+
+`@Remote` 走 Typert 严格模式。**改了方法签名、导出名或参数类型后**运行 `pnpm typert:gen`。
+生成器按工作区原生布局登记 `packages/*`；唯一适配是 `scripts/patch-typert-generator.mjs`
+的 4 行协议归属补丁（生成器只把"工作区源码包"形式的 `@deepseek-ai/dsh-typert-protocol`
+识别为协议符号，第三方仓库以 npm 依赖安装时需要此扩展）。生成器升级后由脚本内两处
+**锚点检查**拦截：协议归属锚点失配报 `cannot apply the single protocol-owner patch`，
+helper 插入点失配报 `cannot locate analyzer helper insertion point`——两种情况都按
+报错更新该脚本的对应锚点即可）。
+
+产物 `lib/typert.*` 随发布提交（日常不提交 `lib/`，发布时 `git add -f packages/*/lib`），
+GitHub 安装免构建。
+
+## 插件配置
+
+`src/index.ts` 的 `Config` 是插件配置，可在 Profile 的 `cordis.patch.yml` 里按行覆盖：
+
+```yaml
+- id: dsh-auto-flow
+  config:
+    prefix: '你好'
+    maxCommandBytes: 1024
+```
+
+## 对齐官方（验收线）
+
+- **结构 / 命名 / 依赖分层**：Host 半 default-export `class X extends TypertRemoteService`，Client 半 `inject` / `apply`；`dsh.bundle.patch` + `dsh.client` 双声明同包；exports / files 分层对齐 `goal` + `ui-goal`。
+- **两类 schema**：插件 `Config` 用 schemastery（`z`），持久化记录用 zod。
+- **注册即 effect**：每个贡献走 `ctx.effect` / 注册表返回的 disposer；可选 seam 用 `ctx.inject([...], cb)`；可选服务（shell）用 `ctx.get('shell')`。
+- **持久化只进 domain storage**：问候落 domain storage（与 session 日志隔离）；不追加自定义会话事件（harness 持久化读路径会拒绝未知事件类型，且 `Session.append` 无法标记 `ignorable`）。
+- **Typed Remote 失败**：`RemoteErrorDetailsMap` 声明 `autoFlow/command-too-long`。
+
+## 发布
+
+npm（每包独立版本）。**发布前两件事**：
+
+1. **登录 npmjs**：`npm login --registry=https://registry.npmjs.org/`（你的全局 registry 若指向 npmmirror，未登录 npmjs 会导致 `pnpm publish` 报 E404）。
+2. **包名可用性**：无 scope 的通用名（`dsh-*`）容易被占用/保留，`npm publish` 会以 E404 拒绝。建议生成时用**你有所有权的 scope**：`node src/index.mjs @你的scope/xxx --dir ...` → 包名 `@你的scope/xxx`（`publishConfig.access: public` 已配好）；用户安装 `dsh plugin --profile web add "@你的scope/xxx"`。
+3. **补全发布元数据**：正式发布前把 `package.json` 的 `repository` / `bugs` / `homepage` / `keywords` 换成你的真实仓库信息（模板不预填，避免假地址误导）。
+
+```sh
+pnpm publish:npm        # prepublishOnly 自动 typert:gen + test + build
+```
+
+GitHub（monorepo 仓库，按包打 tag）：
+
+```sh
+git add -f packages/dsh-auto-flow/lib   # 提交产物，GitHub 安装免构建
+git tag dsh-auto-flow@v0.1.0
+git push --tags
+```
+
+## 安装（用户侧）
+
+命令里的包名/git 地址统一用**双引号**包住：单引号在 cmd 里是字面量，裸 `@scope/包名` 在 PowerShell 里会触发 splatting，裸 `repo#path` 在 bash/zsh 里会把 `#` 当注释。
+
+```sh
+dsh plugin --profile web add "dsh-auto-flow"                                    # npm
+dsh plugin --profile web remove "dsh-auto-flow"                                 # npm 卸载
+dsh plugin --profile web add "github:you/<repo>#dsh-auto-flow@v0.1.0"          # GitHub（monorepo 子包）
+dsh plugin --profile web remove "dsh-auto-flow"                                 # GitHub 卸载
+dsh plugin --profile web add "../<workspace>/packages/dsh-auto-flow"        # 本地目录
+```
+
+## 常见问题
+
+- **为什么把 `lib/` 提交进 git？** dsh 经 GitHub 安装插件时不触发构建（pnpm 默认拦截 git 依赖的 prepare 脚本），提交产物让安装开箱即用（发布时 `git add -f`）。
+- **首次 `pnpm build` / `pnpm test` 报找不到 `<包名>/remote`？** 先运行 `pnpm typert:gen`（契约产物尚未生成；浏览器半 jsdom 测试同样依赖它）。
+- **`typert:gen` 报「cannot apply the single protocol-owner patch」？** 生成器升级后协议归属锚点失配，按报错更新 `scripts/patch-typert-generator.mjs` 的对应锚点。
+- **`typert:gen` 报「cannot locate analyzer helper insertion point」？** 生成器升级后 helper 插入点失配，按报错更新该脚本的插入点锚点。
+- **`pnpm publish:npm` 报 `E404 PUT ... - Not found`？** 两件事：① `npm login --registry=https://registry.npmjs.org/`（未登录 npmjs；全局 registry 若在 npmmirror 会误导）；② 包名对 npmjs 不可创建（无 scope 通用名被占用/保留）——改用你有所有权的 scope 名（`@你的scope/xxx`）。

package/cordis.patch.yml

@@ -0,0 +1,33 @@
+# dsh-auto-flow 的 Bundle 补丁层：向 Profile 组合插入一个插件行。
+#
+# `dsh plugin add` 安装本包后，dsh 会按序应用每个 Bundle 的补丁；
+# 这里的行会被 Loader 挂载（`name` 指向本包，即 Host 半），
+# 浏览器半由包里的 dsh.client 声明自动接入，无需在此声明。
+#
+# 覆盖本插件配置示例（对应 src/index.ts 的 Config，取消注释即可用）：
+#
+# - insert:
+#     - id: dsh-auto-flow
+#       name: 'dsh-auto-flow'
+#       config:
+#         prefix: '你好'
+#
+# 覆写其它插件配置（跨插件协作）：补丁可以按 id 覆写组合里其它插件的配置，
+# 例如给 dsh 内置的视觉适配器声明一条 OpenAI 兼容路由（密钥走环境变量/ .env，
+# 不要写进 patch）：
+#
+# - id: llm-pi-ai
+#   config:
+#     providers:
+#       studio-vision:
+#         displayName: Studio Vision
+#         apiKeyEnv: YOUR_API_KEY
+#         api: openai-completions
+#         baseURL: https://your-gateway.example.com/v1
+#         defaultInput: [text, image]
+#         models:
+#           - id: your-vl-model
+#             input: [text, image]
+- insert:
+    - id: dsh-auto-flow
+      name: 'dsh-auto-flow'