AI-Scarlett/build-dsh-plugin

构建 DSH 插件

使用此工作流程将 DSH 插件创意转化为标准捆绑包，无需修改或遮蔽 Harness 本身。

规范化用户需求

对于每个新的插件请求，请阅读 intake.md。接受普通语言、极简中文需求或 plugin-brief.template.json 中的结构化 JSON 模板。

在生成源代码之前，仅需要三个语义事实：

1. 当前的用户问题；
2. 预期的用户结果；
3. 至少一个可观察的验收标准。

推断名称、包 ID、架构候选方案、风险等级、项目结构、测试和安全默认值。除非用户有偏好，否则不要询问用户设计主机 API、Cordis 条目、模式、构建工具或测试策略。

当可选字段缺失时，默认为仅生成源代码、标准 DSH 捆绑包、只读行为、无真实 Profile 变更、无重启、无外部网络/进程/账户/设备、无凭据、仅本地暴露、不发布以及 E3 可丢弃验收。默认构建具有市场兼容包结构的可复用 DSH 捆绑包，但不要推断提交或更改 DSH STORE 的授权。将每个默认值陈述为假设。不发布 是授权默认值，而非永久禁止：一个经过明确授权、适当许可、内部一致的固定版本可以从网站分发或提交给市场。

仅询问那些会实质性地改变产品结果或风险边界的问题。缺少问题、结果或验收将阻止生成。缺少目标 Profile、变更范围、凭据所有者、LAN/Internet 安全性或真实设备/账户仅会阻止相应的实际操作；当接口可以保持抽象时，它不会阻止安全的源代码框架。

当 JSON 需求可用时，运行确定性规范化器：

node scripts/normalize-brief.mjs /absolute/path/to/plugin-brief.json
node scripts/normalize-brief.mjs /absolute/path/to/plugin-brief.json --json

如果规范化状态为 READY 或 READY_WITH_ASSUMPTIONS，并且请求的模式为 build-source，则继续执行阶段 0-6，无需再次进行广泛的澄清。在获得单独授权并完全指定之前，停止在发布、真实的 Profile 变更、重启、凭据、设备或公共暴露之前。

建立契约

以只读方式开始。检查仓库说明、目标 DSH 版本、官方插件文档、相关的活动 Profile（仅当相关时）以及一个当前的标准插件示例。不要假设来自旧项目的 API 或包合约。

始终强制执行以下规则：

• 构建一个 DSH 捆绑包，而不是桌面应用或 DSH 的分支。
• 永远不要修改 DSH 源代码树或任何 @deepseek-ai/* 包。
• 永远不要禁用、替换或遮蔽官方插件清单。
• 永远不要调用 Loader/Fiber 变更 API。使用公共主机服务和捆绑包组合。
• 使用官方的 DSH CLI 进行包更改。传递固定的参数数组；永远不要构建 shell 命令字符串。
• 将测试保留在可丢弃的主目录/profile 中。永远不要针对真实的 ~/.dsh 编写测试。
• 不要通过日志或客户端暴露凭据、完整用户文件、注入的系统/插件上下文、模型推理或私有路径。
• 将规划、代码完成、包发布、Profile 安装、运行时验收以及外部/设备验收保持为独立状态。
• 将插件就绪状态、目录候选就绪状态、仓库 PR/CI、已合并目录、公共市场可见性和 Profile 安装保持为独立状态。
• 将规范的 Tool 输出、面向模型的渲染、提供者中立的卡片意图以及可选的客户端自定义渲染保持为独立的契约。

在实现或安装之前阅读 boundaries.md。该文件中的硬性阻塞器会覆盖所有分数。 在实现模型 Tool、presentCall、presentResult、presentationMeta 或自定义的 Tool 卡片之前阅读 card-contract.md。

解释每个关键决策

不要在没有决策逻辑的情况下发出规则列表。对于每个架构、权限、变更、发布或验收决策，记录：

1. 目标：该决策控制的失败或结果。
2. 理由：为什么 DSH 机制或当前威胁模型要求这样做。
3. 优点：什么变得更安全、更简单、更兼容或更易于验证。
4. 成本：实施负担、用户体验摩擦、性能成本、能力损失或操作延迟。
5. 适用性：该决策适用的条件。
6. 替代方案：可行的替代方案、被拒绝的原因以及何时重新考虑它们。
7. 流程：具体步骤、负责人、输入、输出和回滚行为。
8. 证据关口：推进所需的可观察证据以及停止工作的条件。

在规划、审查或解释插件时阅读 decision-guide.md。使用其中的决策卡片，而不是在没有分析的情况下复制首选模式。

运行工作流程

按照 workflow.md 了解完整的阶段门控流程和所需工件。不要仅仅因为类似的插件以前通过，就跳过某个阶段；DSH 版本、Profile 组合、依赖项和外部服务可能会发生变化。

1. 证明主机适配性

确定目标主机、扩展点、请求的用户结果、状态变更、外部依赖项和验收面。

当项目针对 Obsidian、VS Code、浏览器扩展、仅 MCP 或其他没有经过验证的 DSH 捆绑包合约的运行时，停止并报告主机不匹配。提供兼容的主机或有意限制范围的适配器。不要转向相邻的项目。

生成主机合约记录和架构比较。关口：compatible、adapter-required 或 incompatible；永远不要将其作为隐式散文。

2. 分类风险

按照 scorecard.md 分配一个等级：

• R0：只读元数据/UI。
• R1：主机工具/服务或用户拥有的插件状态，无 Profile 生命周期写入。
• R2：外部进程、网络、凭据或设备桥接。
• R3：Profile 生命周期、重启、远程控制或广泛管理。

不确定时使用较高的等级。在编码之前记录非目标和禁止面。

生成风险登记册，其中包括资产、参与者、信任边界、写入面、故障影响、最低证据级别以及选择该等级的原因。

3. 选择标准模式

• 仅主机捆绑包：公开一个公共的 Cordis 服务/工具，并贡献一个或多个唯一的补丁行。
• 主机 + 客户端：保持浏览器代码分离；使用 window.__ModuleLoader__.load() 和插槽进行注册。浏览器代码不得导入主机/Node 模块。
• 可选的 Web 路由：使用 ctx.inject(['webServer'], ...) 延迟注册；无头/无 Web 的 Profile 仍必须启动。
• 技能适配器：挂载隔离的技能文件；不要静默安装外部运行时、扩展或凭据。
• ApiProxy 桥接：使用允许列表、修订、身份验证、有界解析和故障关闭传输安全性来适配狭窄的公共远程接口。
• 生命周期管理器：将每个 Profile 更改视为 R3 事务，并使用下面的变更协议。
• 工具卡片合约：优先使用提供者中立的 presentCall/presentResult 渲染意图；仅当检查的内置词汇无法表达结果时，才使用自定义的客户端插槽卡片来展示插件拥有的 Tool。

创建包含 dsh.bundle.patch、包可解析的 cordis.patch.yml、唯一条目 ID、显式文件、版本、许可证和构建合约的捆绑包清单。请记住，后面的补丁层会替换一个行的完整 config；它们不会深度合并它。

当选择影响权限、进程边界、安装行为或用户体验时，至少比较两个合理的模式。记录优点和成本；不要仅仅因为早期项目使用了某种架构就选择它。

4. 实现最小权限

使用已检查的 DSH 版本已经提供的公共服务。如果缺少所需的扩展点，请停止并提议适配器或上游更改，而不是修补核心。

优先使用只读发现和试运行/预览 API。使写入功能单独启用。在业务逻辑之前验证模式和大小限制。拒绝格式错误的 Profile、不明确的路径、未知的官方组件、过时的状态、重放、并发更改和缺失的证据。

对于每个模型 Tool，记录规范输出、面向模型的渲染器、待处理卡片、已完成卡片、持久的展示元数据、边界/修订、通用回退以及实时/重放证据。展示器必须是确定性的，并且不执行 I/O、时钟/随机访问、会话读取或额外的权限相关工作。永远不要将凭据、完整的私有文件、模型推理或无界参数放入卡片中。

对于重复出现的故障模式，请阅读 problem-playbook.md。

生成权限矩阵，包含每个数据源/操作、拥有方、允许的调用者、修订、大小/速率限制、故障模式和测试。任何没有用户结果和测试的权限都将被移除。

5. 应用变更协议

对于 Profile/包/重启变更，为恰好一个操作创建一个全新的类型化计划，其中包含：

1. 操作和目标 Profile；
2. 不可变的包/源标识；
3. 确切的文件范围和预期的前置条件哈希；
4. 命令 argv 和工作目录；
5. 备份位置和回滚流程；
6. 后置条件和健康检查；
7. 一个确切的确认短语；
8. 过期时间和一次性使用标识。

显示计划并等待确切的每操作确认。在不匹配、过期、并发更改或先前使用的情况下使其无效。在写入之前进行备份，以原子方式提交，运行配置和运行时健康检查，并在失败时回滚。仓库发布永远不能授权本地 Profile 更新。

将确认摩擦和事务机制视为显式成本。对于 R3 接受这些成本，因为替代方案是对用户状态的静默、难以恢复的破坏。不要将变更协议强加于纯 R0 读取。

6. 攀登证据阶梯

仅凭当前证据推进：

• E0：想法或计划。
• E1：静态结构/源代码审查。
• E2：自动化单元/合约/故障测试。
• E3：可丢弃的 Profile 安装、--dump-config、启动和 API 冒烟测试。
• E4：单独确认的真实 Profile 版本、进程/端口、官方清单/API 和可见的 UI 回读。
• E5：外部/公共/设备验收以及故障恢复或回滚证据。

永远不要从较低级别推断更高级别。UI 截图不能证明回滚；HTTP 200 不能证明可见的 UI；安装成功不能证明重启健康；模拟器输出不能证明真实设备。

对于 Tool 卡片，E2 包括确定性展示器、畸形重放、修订、边界、截断和通用回退测试。E3 包括在隔离的 DSH 运行时中的实时加上持久化重放对比。用户 Profile 中的可见卡片行为仍然是 E4。

生成每个能力的证据矩阵。包括负面和恢复证据，而不仅仅是正常路径。分数用于评估就绪状态；它永远不会授予权限或取代硬性关口。

7. 分别发布和安装

在仓库发布之前，同步包版本、README、目录条目、不可变安装锚点、测试和固定的源代码元数据。对于 Git 源，要么交付构建的工件，要么声明一个自包含的 prepare 脚本并披露 pnpm allowBuilds；锁定完整的提交 SHA。

运行仓库检查、源代码验证和试打包。在合并后验证远程提交和公共资产。然后停止。仅在新的已确认变更计划下更新真实的 Profile，通过批准的机制重启它，并回读已解析的版本和运行时状态。

生成两个独立的报告：仓库发布证据和 Profile/运行时验收证据。当第二个报告缺失时，声明 Profile unchanged 或 Profile unverified。

8. 使可复用插件具备 DSH STORE 就绪性

在构建可复用的第三方 DSH 插件、评估现有仓库是否适合 DSH STORE 或准备目录条目时，请阅读 marketplace.md。

不要等到提交时才发现列表不兼容。从第一个框架开始，保留唯一的包/目录/条目 ID；声明仓库、版本、许可证、安全的 dsh.bundle.patch、包相对路径的补丁、运行时/构建文件、生命周期脚本、权限、依赖项和兼容性证据。在每次 STORE 评估开始时，运行 node scripts/official-dsh-releases.mjs 并使用其官方的最近三个版本窗口；不要重复使用记忆的窗口。解析器遵循最高的活跃 npm latest/alpha/beta/rc 频道，排除仅 next 和已弃用的版本，并在权限无效时故障关闭。观察到的 2026-09-02 窗口是 0.1.2-alpha.2、0.1.2-alpha.3 和 0.1.2-alpha.4，但这是证据而非永久常量。在已解析窗口中的每个发布版本上，保留精确的 compatibility.dshReleases 和匹配的 compatibility.dshOperations 记录，用于安装、启动、卸载和回滚。历史键可以保留，但未知的元数据应保持未知，而不是被猜测。

保持 STORE 发现和受信安装物理和逻辑上分离。registry/candidates.json 中的记录仅用于发现，不携带包/安装/权限合约，并且必须规范化为 installable: false 且无允许的操作。只有在经过单独的固定源、捆绑包、许可证、权限、兼容性和证据审查之后，它才能移动到 registry/catalog.json。推广、推荐、赞助、Stars 或截图不能取代结构化的审查。