意图翻译器 kirahvi03/Hackathon--Plug-In

黑客松 —— 插件方向

本仓库是 DSH 黑客松的插件方向工作区（远程仓库 kirahvi03/Hackathon--Plug-In）。
内容分两部分：

1. 本机开发环境的配置与自检脚本（第 1–3 节）
2. DSH 插件：骨架 plugins/hackathon-starter/ 与参赛作品 plugins/dsh-intent-translator/（第 4 节）

游戏方向的仓库在另一处：Hackathon--Game （本地路径 ..\hackathon-game）。

插件体系的完整研究报告见 docs/dsh-plugin-development-report.md （58KB，含官方 API 导出名、slot key 目录、模板出处与未能确定事项清单）。

1. 环境总览

| 组件 | 版本 | 位置 / 说明 |
| Node.js | v24.21.0 | C:\Program Files\nodejs\node.exe（系统安装，已在 PATH 中） |
| npm | 11.19.0 | 随 Node 提供 |
| pnpm | 11.7.0 | 由 ~\.dsh\bin\pnpm.cmd 转发到 DSH 内置 pnpm 11.7.0 |
| Python | 3.12.14 | DSH 内置解释器，已通过 PATH 前置覆盖失效的商店别名 |
| pip | 26.2.1 | ~\.dsh\bin\pip.cmd → python -m pip |
| Git | 2.55.0 | C:\Program Files\Git\cmd\git.exe |
| GitHub 凭据 | 已就绪 | Git Credential Manager 2.9.1，账号 kirahvi03 |
| VS Code | 1.140.0 | 命令行入口 code 可用 |
| ffmpeg | 7.1.1 | 已在 PATH 中 |

未安装（按需再补）：gh（GitHub CLI）、docker、PowerShell 7（pwsh）。

Python 预装库：numpy 2.3.5、pandas 3.0.1、openpyxl 3.1.5、XlsxWriter 3.2.9、 python-docx 1.2.0、python-pptx 1.0.2、Pillow 12.3.0、lxml 6.1.3。

2. 本次为环境做的改动

1. 修复 Python：PATH 上原本只有 Microsoft Store 的 python.exe 占位符（执行即失败）。
现已把可用的 DSH 内置解释器目录前置到用户 PATH。
2. 补上 pnpm：pnpm 之前不在 PATH 上。新增 ~\.dsh\bin\pnpm.cmd、pnpx.cmd shim，指向 DSH 内置 pnpm，并把 ~\.dsh\bin 加到用户 PATH 最前面。
3. 补上 pip 入口：内置 Python 的 Scripts 目录没有可执行文件，新增 pip.cmd shim。
4. PowerShell 执行策略：当前用户范围设为 RemoteSigned，本地脚本可直接运行。
5. 初始化本仓库：main 分支、.gitignore、.gitattributes。
6. GitHub 凭据：全局 credential.helper = manager，git push 无需再次登录。

以上 PATH 改动写入的是用户级环境变量。已打开的终端需要重开一次才能生效。

3. 快速开始

3.1 环境自检

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\env-check.ps1

全部通过时退出码为 0，并逐项打印各工具的实际版本与路径。缺少可选项（gh/docker）只告警。

3.2 Web / Node 项目

pnpm init # 或 pnpm create vite my-app
pnpm add -D typescript # 依赖安装
pnpm dev # 跑开发服务器

用 npm 也可以，但本工作区统一用 pnpm 以节省磁盘并避免依赖提升问题。

3.3 Python 项目

全局解释器可直接用；做正式项目建议建虚拟环境，避免污染内置环境：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

若激活脚本被执行策略拦截，先运行 Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force。

3.4 推送到 GitHub

远程仓库已接好并完成首次推送：

| 项 | 值 |
| 仓库 | <https://github.com/kirahvi03/Hackathon--Plug-In>（public） |
| remote | origin |
| 分支 | main，已设置上游跟踪 origin/main |

日常提交：

git add -A
git commit -m "feat: ..."
git push

认证由 Git Credential Manager 自动完成（本机已存 kirahvi03 的 token，含 repo + workflow 权限），正常情况不会再弹出登录。

4. DSH 插件：骨架与参赛作品

4.1 插件骨架（plugins/hackathon-starter/）

本机 DSH 是 0.2.1-rc.2，插件框架为 Cordis 4。一个插件包 = 一个 bundle， package.json 的 dsh.bundle.patch 指向 cordis.patch.yml，后者把插件行 insert 进 profile 的插件树。

骨架同时演示两个扩展点：

| 半边 | 文件 | 内容 |
| Host | index.js | 具名导出 { Config, apply, inject, name }，用 ctx.tools.register(defineTool({...})) 注册工具 plugin_ping |
| Client | client.js | window.__ModuleLoader__.load + ctx.slots.register 往 conversation.composer.dock 插一个徽标 |

每个 API 字段都对照官方实现 @deepseek-ai/dsh-tool-todo 抄写（不是猜测）： name / description / parameters / output.{schema,render} / execute(args, exec) / presentCall(args)。

语法自检（无需安装任何依赖）：

node --check .\plugins\hackathon-starter\index.js
node --check .\plugins\hackathon-starter\client.js

安装到 profile（转发给内置 pnpm，必须用绝对路径）：

dsh plugin --profile desktop add "C:\Users\19371\Documents\deepseek-harness\default-workspace\plugins\hackathon-starter"

⚠️ 尚未替你执行安装：desktop 是当前运行中的这个应用独占管理的 profile，安装后需重启才生效，可能打断正在进行的会话。要装的话说一声。

ℹ️ 官方包（@deepseek-ai/dsh-tools 等）不在 npm 上，它们打包在 app.asar 内。
插件通过 peerDependencies 声明版本要求，由宿主提供实现，因此不要自己 pnpm add 这些包。

4.2 参赛作品：plugins/dsh-intent-translator/

面向 vibecoding 的意图翻译器：用亮蓝色 #66ccff 标出输入里的 1–3 处模糊描述，每一处独立分叉成 2–3 个「人话方向」卡片；点选一张只替换它所属的模糊片段，「背景有图片」这类确定信息原样保留。支持撤回和「换一组」。

意图翻译器多片段候选卡片

| 项 | 位置 / 说明 |
| 工具行按钮 | conversation.input.left，与 dsh-prompt-optimizer 的 ✨ 同槽位 |
| 候选卡片 | conversation.input.dock，输入框上方 |
| Host | lib/host.js：ctx.webServer 路由 + ctx.llm.stream()，15s 超时 |
| 纯逻辑 | lib/engine.js：多片段校验、人话标签守卫、方向去重、span 定位与替换 |
| Client | client.src.js → client.js：按钮、卡片、#66ccff 高亮、逐段替换、撤回、换一组 |
| 完整说明 | plugins/dsh-intent-translator/README.md |
| 实现计划 | docs/dsh-intent-translator-plan.md |

安装到 desktop profile（需要重启一次让 Host 新行生效）：

dsh plugin --profile desktop add "C:\path\to\Hackathon--Plug-In\plugins\dsh-intent-translator"

验证：

cd plugins\dsh-intent-translator
npm test # 构建 client.js，再跑 33 个 Node 测试

V2 只预留接口：点选方向后可通过 ctx 调用 dsh-prompt-optimizer 精修， V1 不自动调用，也不复制其代码。详见插件 README。

5. 注意事项

- 不要在 DSH 会话里直接 .\script.ps1：DSH 托管的 shell 对脚本加载有额外限制，会报 “未对文件进行数字签名”。加上 -ExecutionPolicy Bypass 用子进程运行即可： powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\env-check.ps1。
你自己开的普通终端不受此限制。
- 不要 pip install 到内置 Python 之外：python 已指向 DSH 内置解释器，装包会写进 DSH 的 site-packages。长期项目用 .venv 隔离。
- 密钥不入库：.gitignore 已覆盖 .env、.pem、credentials.json 等；需要提交样例时用 .env.example。
- 行尾符：.gitattributes 统一仓库内为 LF，Windows 下工作区仍可用 CRLF。

6. 目录结构

.
├─ README.md 本文件 ├─ .gitignore 忽略规则（Node / Python / 密钥 / 编辑器） ├─ .gitattributes 行尾符与二进制文件规则 ├─ docs/ │ ├─ dsh-plugin-development-report.md DSH 插件开发研究报告（58KB） │ └─ dsh-intent-translator-plan.md 意图翻译器实现计划 ├─ plugins/ │ ├─ hackathon-starter/ ← 插件骨架 │ │ ├─ package.json bundle 清单（dsh.bundle.patch / dsh.client） │ │ ├─ cordis.patch.yml 把插件行 insert 进 profile │ │ ├─ index.js Host 半边：注册 plugin_ping 工具 │ │ ├─ client.js Client 半边：输入框下方徽标 │ │ ├─ icon.svg 插件卡片图标 │ │ ├─ locale/{zh,en}.json 显示名称与描述 │ │ └─ README.md 骨架的改造指引 │ └─ dsh-intent-translator/ ← 参赛作品：意图翻译器 │ ├─ package.json bundle + dsh.client + peerDependencies │ ├─ cordis.patch.yml Host 行 insert │ ├─ index.js Host 入口 │ ├─ lib/{engine,host}.js 纯逻辑 + 路由/LLM/超时 │ ├─ client.src.js → client.js Client 源码与构建产物 │ ├─ scripts/build-client.mjs 零依赖构建（内联 engine.js） │ ├─ test/.test.mjs 33 个 Node 测试 │ ├─ docs/preview*.png 验收截图 │ └─ README.md 安装/配置/数据契约/V2 边界 └─ scripts/ └─ env-check.ps1 环境自检脚本