dsh-e2e-dev-sdd

DeepSeek Harness Web 的五阶段 SDD（Specification-Driven Development）工作台。插件把需求讨论、原型输出、系统设计、规格设计、开发测试作为五个独立入口；五个阶段默认是可选能力而不是固定流水线，用户选择当前需求真正需要的来源和已接受交付件，与 DSH Agent 对话迭代并提交成果。

当前能力

• 项目看板以“需要我处理”开头：来源变更待重审、草稿待验收、质量检查未通过、测试失败、开发目标未配置、交付件编号冲突和 OpenSpec 校验失败都会列成一条可执行事项，并可直接跳到对应阶段或设置；下面只保留 4 个关键指标和按紧迫度排序的交付工作单元表（每行给出下一步，默认隐藏已完成，可切换显示）。五阶段分布、燃起图、缺陷覆盖、外部工作量、产品积累、来源追踪和最近活动收进“更多数据与趋势”，不再挤占首屏。需求内缺陷归入所属需求，不重复增加五阶段行或燃起范围；大清单一次最多渲染 200 行。
• 五个阶段一级菜单，共用同一套项目和交付件协议。
• 一个 DSH Workspace 对应一个可提交的 .sdd/ 项目空间；主需求下的每个可独立交付子项拥有自己的工作单元。
• 业务适配器统一返回 source-bundle@1；单条来源就是 items 长度为 1 的需求包。
• 内置零配置手工来源：没有企业适配器时可直接填写标题、初始描述和可选子项，再由 AI 在需求讨论中逐步补齐。
• 再次同步同一主 ID 会预览新增、修改、移除和无变化项，用户确认后才应用。
• 导入确认前可逐条查看完整正文、元数据、业务关系和当前已导入版本；JSON 支持结构化预览/源码切换，富文本字段经过安全净化后按 HTML 展示，无历史版本时使用全宽单栏，有历史版本时才左右对比。深层对象按需展开、长数组分批显示。存在自定义 Provider 或 Connector 时默认选择企业适配器，仍可切换到手工录入。预览和正文详情使用轻量项目上下文，不重复计算 Git、OpenSpec、质量与看板，前端也只更新局部忙碌状态。项目看板导入的缺陷是独立工作单元，从当前需求内导入的缺陷则保留自身编号和来源、但复用父需求的交付流程。
• 需求变化保存新的来源快照，不覆盖历史；受影响阶段进入重新评审，外部移除不会自动删除本地成果。
• 自动发现和校验当前工作单元的来源及所有阶段 accepted 交付件；默认灵活模式可自由组合输入，也可在项目配置中启用严格依赖模式。
• 初始化生成 .sdd/templates/<stage>/template.yaml 与 deliverable.md；项目可编辑并提交，草稿会绑定创建时的模板快照。
• 同一份模板快照用于草稿生成、AI 输出约束和结构质量检查。
• 交付件是可包含正文、图表、原型和附件的多文件包；页面提供完整文件树、Markdown 预览/源码切换，并可通过 DSH Host 跨平台打开文件和目录；验收时冻结文件清单和整包哈希。
• 代码仓库在项目设置统一登记；已关联仓库会自动作为需求、原型、系统设计和规格设计会话的只读辅助输入，不需要逐阶段选择。系统设计确认影响范围，规格设计确认实际开发目标，开发阶段只为目标仓库创建可写特性分支。未关联仓库的项目保持原流程。
• 内部规划引擎贯穿五阶段，但普通用户不需要感知或启用 OpenSpec：开始阶段对话时，插件在后台尽力准备需求级规划工作区和同一规划单元；CLI 不可用时自动退回内置结构化引导，不阻断业务流程。AI 根据当前阶段和需求复杂度采用轻量、标准或复杂深度，每轮只推进最重要的一组决策，并把已确认结论同时沉淀到阶段成果和内部规划文件。创建目标 Worktree 后，插件自动把规划内容迁移到隔离代码仓。
• 原型、系统设计、规格设计和开发测试可以按需求标记为“不适用”；看板单独统计，不创建空交付件。简单需求可以直接从原始来源进入开发测试。
• 本阶段输入材料可以直接预览：上游交付件打开其固定版本的完整交付包，需求/缺陷来源打开 Manifest 绑定的完整来源快照，而不是只显示标题或跳到最新版本。页面同时提供需求到五阶段的追踪矩阵；accepted 版本会先检查来源、上游交付件和模板哈希，再区分“处理上游变更”和“用户主动调整”。空变更不能创建或验收，旧会话只读，新变更会话包含类型与版本并关联历史运行；未验收草稿可安全移入 .sdd/trash。
• 将选中交付件整合为阶段输入，启动/复用原生 DSH Session。
• 人工接受交付件并冻结内容 SHA-256。
• 开发交付验收后执行需求收口：把需求创建或修改的长期产品特性版本化，刷新产品当前规格，冻结完整交付归档，并生成同源的转测报告与邮件稿。
• 稳定内部 UUID、插件阶段编号、企业外部编号和显式关系的扩展契约。
• 可注册的需求/缺陷 Source Provider Cordis 服务。
• 内置无 shell 的命令型 Source Provider，支持项目自有 CLI 脚本。
• 企业通用 Connector 与适配器放在插件 business/，项目专用适配放在 .sdd/business/；两处格式完全一致，同名时项目配置覆盖插件配置。
• 每阶段独立 System Prompt、输入门禁、工具执行 Guard、结构质量检查和验收清单。
• 一个阶段运行固定绑定一个交付件和一个 DSH Session，支持恢复与逐轮质量刷新。
• 对话中确定结论必须同步到交付件，并提供显式“同步结论”操作。
• 开发测试阶段从选定基线创建 sdd/... 特性分支；AI 根据仓库与 CI 自主执行测试，插件记录真实退出码和代码指纹，证据过期或失败时阻止本地提交。
• .sdd/events/*.jsonl 记录可提交的项目活动，为看板趋势提供事实数据。
• 外层 SDD 项目仓库提供 Git 状态、Fetch、仅 Fast-forward 同步、按范围提交和显式 Push；分叉或冲突时停止自动操作。不同 UID 血缘发生交付件显示编号冲突时，只允许未绑定的草稿追加稳定短后缀，已验收冲突必须人工处理。

外层 SDD 项目仓库可以由用户显式 Push 当前协作分支；目标代码仓库仍不会自动 Push、创建 PR/MR 或合并，这些交付动作由负责人在检查本地提交后完成。MCP Provider 也尚未内置，可通过公开 Provider 接口继续扩展。

安装

插件面向 DSH 0.2 的客户端契约（dsh.client.platform、dsh-client-modules 模块表与 slot 渲染）编写，package.json 中声明 dsh.engines.dsh: ">=0.2.0-rc.1"。DeepSeek Harness 桌面版内置的 0.2.0-rc.2 运行时即为目标环境。

npm

发布后安装到 Web profile（桌面版见下一节）：

dsh plugin --profile web add dsh-e2e-dev-sdd@latest

重启 dsh web 后，侧边栏会出现「项目开发」分组以及其下的项目看板、五个阶段和项目设置入口；点击任一条目会在主面板打开对应页面。

桌面版（DeepSeek Harness.app）

桌面版内置 0.2.0-rc.2 运行时，profile 由应用独占管理（dsh --profile desktop 会被拒绝），因此不能用 dsh plugin 安装。手工把插件挂到桌面 profile。先备份要改的两个文件：

DshHome="${DSH_HOME:-$HOME/.dsh}"
ProfileDir="$DshHome/profiles/desktop"
PluginDir=/path/to/dsh-e2e-dev-sdd          # 本仓库的绝对路径

cd "$ProfileDir"
cp cordis.patch.yml cordis.patch.yml.bak
cp package.json package.json.bak

# 1) 让 profile 能解析到插件包
ln -sfn "$PluginDir" "$ProfileDir/node_modules/dsh-e2e-dev-sdd"

# 2) 登记依赖（便于以后重装或核对）
#    在 $ProfileDir/package.json 的 dependencies 中加入：
#      "dsh-e2e-dev-sdd": "link:/path/to/dsh-e2e-dev-sdd"

# 3) 在 $ProfileDir/cordis.patch.yml 末尾追加一行装载项：
#      - insert:
#          - id: e2e-dev-sdd
#            name: dsh-e2e-dev-sdd

Windows 下第 1 步改为 PowerShell 的目录联接或复制：

$DshHome = if ($env:DSH_HOME) { $env:DSH_HOME } else { Join-Path $HOME '.dsh' }
$ProfileDir = Join-Path $DshHome 'profiles\desktop'
New-Item -ItemType Junction -Path (Join-Path $ProfileDir 'node_modules\dsh-e2e-dev-sdd') -Target 'C:\path\to\dsh-e2e-dev-sdd'

注意：desktop profile 的 ~/.dsh/profiles/desktop/node_modules/dsh-news-wall 是同一套做法，可以对照。改完 package.json 或补丁文件后必须完全退出并重新打开应用，只刷新页面不生效。

link: 安装指向源码目录：改动代码后要 pnpm build，再重启应用。回滚只需还原两个文件并删除链接：

cd "$ProfileDir"
cp cordis.patch.yml.bak cordis.patch.yml
cp package.json.bak package.json
rm node_modules/dsh-e2e-dev-sdd

验证安装是否生效：应用启动后，页面侧边栏应出现「项目开发」分组。dsh --profile desktop --dump-config 会被应用独占检查拒绝，需要验证补丁层时可以先把 profile 目录复制成另一个名字再 dump：

DshHome="${DSH_HOME:-$HOME/.dsh}"
cp -R "$DshHome/profiles/desktop" "$DshHome/profiles/desktopcheck"
dsh --profile desktopcheck --dump-config | grep -A1 'e2e-dev-sdd'

输出中应出现 id: e2e-dev-sdd 与 name: dsh-e2e-dev-sdd；用完删除 desktopcheck 目录即可。

本地开发

macOS/Linux：

pnpm install
pnpm build
dsh plugin --profile web add link:$(pwd)

Windows PowerShell：

pnpm install
pnpm build
dsh plugin --profile web add "link:$($PWD.Path)"

构建、测试和运行时脚本均通过 Node.js 启动，不依赖 rm、bash 等 POSIX 命令。

更新代码后重新构建并重启 DSH。可用下面的命令检查 bundle 层：

dsh --profile web --dump-config

Git 安装

仓库已包含跨平台构建产物，macOS、Linux 和 Windows 使用同一条命令，不需要配置 pnpm 构建白名单：

dsh plugin --profile web add github:Army1900/dsh-e2e-dev-sdd

确认安装层已经挂载：

dsh --profile web --dump-config

输出中应包含 # == dsh-e2e-dev-sdd 和 id: e2e-dev-sdd。随后必须结束旧的 dsh web 进程并重新启动；只刷新浏览器不会加载新插件。

Windows PowerShell 中可以用下面的命令检查实际 DSH Home 和安装结果：

$DshHome = if ($env:DSH_HOME) { $env:DSH_HOME } else { Join-Path $HOME '.dsh' }
$ProfileDir = Join-Path $DshHome 'profiles\web'
Get-Content (Join-Path $ProfileDir 'package.json')
dsh --profile web --dump-config

安装成功后，profile 的 package.json dependencies 中应包含 dsh-e2e-dev-sdd。只应安装可信源码，并建议在生产环境锁定 commit。

使用

1. 在 DSH 中打开一个 Git 仓库作为 Workspace。
2. 进入任一阶段菜单；插件会检查 .sdd/project.yaml。未初始化时点击“初始化项目”；配置不合法时会显示字段级错误，可修复后重新检查，或备份旧配置后重新生成默认配置。
3. 在“项目设置”配置外层 SDD 项目仓库的 remote、协作基线、同步策略和提交范围。Fetch 只更新远程引用；自动同步仅允许干净工作区的 fast-forward；提交和 Push 都需要显式确认。
4. 在项目看板点击“导入需求包”或“导入独立缺陷”。默认“手工录入”，会打开专用编辑界面：左侧是主项与子项列表，右侧是带 Markdown 工具栏和预览的正文编辑器，可插入需求/缺陷结构模板、把粘贴的 Markdown 按标题自动拆成子项，内容按工作区暂存，误关后可恢复；有企业适配器时也可切换到对应 Connector。插件级 business/ 适配器安装一次后供所有项目使用，项目级 .sdd/business/ 可使用同一格式补充或覆盖。同步清单可以逐条查看完整内容和已有版本，确认后才应用。开发或测试当前需求时，从该需求页面点击“获取并预览本需求缺陷”，缺陷会归入当前需求而不是新建五阶段空间。
5. 从页面顶部选择当前需求工作单元；阶段页面只展示已选输入摘要，点击“选择/调整输入”在弹窗中选择当前来源和上游阶段最新 accepted 交付件。创建草稿后输入固定到 Manifest，变化时通过修订处理。无需某个阶段时直接标记“不适用”，以后仍可恢复。
6. 在“项目设置”添加本地或远程目标代码仓库并选择默认基线。前四阶段开始对话时自动获得全部关联仓库的只读参考；本地干净仓库直接读取，远程仓库只 Clone 一份共享对象缓存。系统设计确认当前需求的影响范围，规格设计确认实际开发目标，跳过前置阶段时可在开发阶段补齐。刚执行 git init、尚无提交的本地仓库可以在明确确认后创建空初始提交；空远程仓库仍需先显式创建提交并 push。
7. 选择草稿并开始阶段对话；插件在对应 Session 安装阶段 System Prompt、仓库边界、可选 OpenSpec 位置和工具 Guard。
8. 与 Agent 迭代；Agent 必须按照页面所示模板输出，并把确定结论逐轮写入 .sdd/work-items/<uid>/artifacts/<stage>/.../deliverable.md。实际文档可以很长，也可以在交付件目录中增加图片和附件并从主文档引用。
9. 返回阶段页面查看交付包和结构质量、确认阶段验收清单并接受版本。需要修改 accepted 版本时点击“检查变更 / 提出调整”：插件先展示来源、上游交付件和模板的哈希差异；存在差异时处理上游变更，没有差异时必须填写主动调整原因。新修订使用新的变更会话，名称包含变更类型与版本，旧会话和旧交付件保持只读。不再需要的草稿可移入 .sdd/trash。
10. 开始阶段对话后，插件自动根据需求复杂度引导当前阶段：简单事项只确认必要目标、规则、例外和验收；标准事项按目标、范围、主流程、边界异常和验收推进；复杂事项增加依赖、风险、备选方案和验证策略。用户无需启用或操作底层 OpenSpec。
11. 在开发测试阶段只为已确认目标仓库创建隔离代码空间；本地仓库创建 Worktree，远程仓库 Clone，并从所选基线提交创建独立的 SDD 特性分支。开发交付件创建修订时沿用同一工作单元的 Worktree/分支，同时使旧测试证据过期。后台规划内容会自动迁移到目标分支继续维护。通过“让 AI 验证”运行相关测试；有效证据形成后才能提交。
12. 开发交付验收且没有遗留草稿后，点击“归档并沉淀到产品”，选择创建新特性或更新现有特性，并用产品语言确认交付后的当前能力。插件在项目根目录的 product/ 生成 FEAT 特性版本与当前产品规格，在根目录的 deliveries/ 生成 DLV 交付归档，冻结来源、历史阶段成果、内部规划副本、代码提交与测试证据，同时生成转测报告和邮件稿；.sdd/ 继续只承担研发过程数据。
13. 在项目看板“更多数据与趋势 → 产品积累”查看特性生命周期、产品当前规格和历史交付；再到“项目设置”提交 SDD 项目变更并显式 Push。出现分叉、文本冲突或已验收编号冲突时，插件停止自动同步并要求人工处理。

设计原则

• 不自动串行运行全部阶段；默认灵活模式允许跳过和自由组合输入，严格模式才执行项目声明的 required 依赖。
• Git 仓库文件是项目真源，浏览器状态不是。
• 已接受交付件不可被静默覆盖。
• 内部身份使用 UUID；交付件编号由插件按阶段固定生成；企业外部编号原样保留并显式关联。
• 层级和追踪关系显式记录，不从编号字符串推断。
• Source Provider 只返回业务事实；缺陷是独立交付还是归入当前需求，由用户选择的导入入口决定，不要求企业适配器返回需求关系。
• 外部材料必须先转换为 Source Envelope，再由 AI 整合为正式交付件。
• 每个需求的代码开发使用独立 Worktree 或 clone，不污染主项目空间。
• 需求是一次变更，特性是长期产品能力；历史交付保持不可变，产品当前规格只表达当前有效事实。
• product/ 和 deliveries/ 是项目根目录下可直接阅读、提交和移交的固有资产；.sdd/ 是插件过程与运行数据。

完整的用户流程、角色分工和页面截图见 五阶段 SDD 完整开发流程 Blog。阶段运行机制见 docs/stage-runtime.md，项目模板定制见 docs/templates.md，多文件交付规范见 docs/artifact-package.md，详细设计见 docs/architecture.md，业务适配开发见 docs/business-development-guide.md，Cordis Provider 扩展见 docs/extensions.md，规范文件位于 schemas/。

开发验证

pnpm typecheck
pnpm test
pnpm build

License

MIT