dsh-spec-collab

dsh-spec-collab

DeepSeek Harness 的需求“编辑校样台”，用于把原始需求澄清为研发和开发 AI 可直接理解的 Ready Spec。需求文档是主画布，评论、客户洞察、决策、版本差异和 AI 建议通过批注边栏与全屏抽屉完成闭环。

产品边界严格止于 Ready Spec，不包含代码实现、测试用例生成、worktree、MR、部署、发布或交付状态管理。

兼容 DeepSeek Harness v0.1.1-rc.1。插件可在局域网 HTTP 地址下运行，不依赖浏览器提供 crypto.randomUUID；DSH 精简侧栏仅显示“设置”时，也会正常挂载“需求讨论”入口。

一键安装

已有 Node.js 环境时，无需先全局安装 DSH CLI：

npx -y @deepseek-ai/dsh plugin --profile web add dsh-spec-collab@latest

如果 dsh 已在 PATH 中，也可以使用简写：

dsh plugin --profile web add dsh-spec-collab@latest

安装后重启现有的 dsh web 进程。后续更新使用：

dsh plugin --profile web update dsh-spec-collab@latest

插件已经内置非安全 HTTP 环境所需的 UUID fallback，不需要通过代理向 HTML 注入 crypto polyfill。团队部署仍建议使用 HTTPS，并在 DSH 前配置认证。

核心流程

输入原始需求
  -> 产品 AI 自动初审（九个维度）
  -> 产品逐项回应
  -> 产品 AI 二次审核 + 候选 patch
  -> 产品确认当前 commit
  -> 产研 + 双方 AI 共审
  -> 产品/研发分别确认当前 commit
  -> 六项 Ready 门
  -> 输出 Ready Spec

完整演示

点击下方截图观看从选择工作区到生成 Ready Spec 的完整 MP4 录屏：

播放 MP4 录屏 · 阅读完整图文教程

查看完整流程截图

1. 新建需求并选择工作区

2. AI 审核问题和人工回复

3. 审核并接受候选 Patch

4. 记录人工 Decision

能力

• 匿名只读；首次评论、修改、回复、确认前登记 participant_id + 花名 + 责任角色。
• 原始需求、Markdown PRD、相关链接与代码范围分别记录为来源，不静默混成事实。
• 正式正文只存在 requirements/<id>/spec.md，每次显式保存生成一个 Git commit。
• 保存携带 baseCommit；过期或存在外部未提交修改时拒绝覆盖。
• FACT / INFERENCE / ASSUMPTION / TO_VERIFY 结构化 Review Item；FACT 强制可访问且带版本的证据。
• 同一需求在同一流程阶段复用一个 DSH AI session；审核、评论分析和追问只追加增量提示，进入下一阶段后再创建新会话。
• 每条实质评论提交后自动进入当前阶段 AI 会话，回复必须包含理解、证据或 TO_VERIFY、影响章节/AC 和建议处置。
• AI 只能提交 Review Item、评论分析和候选 patch；不能写 Git、代替人确认或标记 Ready。
• 保存和 patch 接受后自动触发 change review；候选 patch 基于精确 commit，过期自动失效。
• Decision、Comment、Confirmation 分离；确认绑定 commit，可按 section/AC 局部失效。
• Ready 门检查目标与用户结果、稳定 AC、范围与非范围、业务语义、证据来源、测试约束。
• Ready 输出包含 commit SHA、稳定 AC、Decision、来源、非阻塞 Open Questions 和产品/研发确认人。
• Agent 工具：spec_list、spec_read、spec_reply、spec_submit_review、spec_propose_patch。
• v3 协作账本、插件内通知和 SSE，多浏览器刷新后仍可继续；评论支持页面级/行内、提及、指派、筛选、重开和深链。
• 客户、公司、来源和洞察为独立实体；洞察可关联多个需求、章节或 AC，支持 CSV/Markdown 原子导入和去重。
• 本地草稿存入 IndexedDB，异常关闭后可恢复；正式保存仍由 Git commit 承载。
• 版本历史与 AI patch 共用结构化行级 diff，未变上下文可折叠；恢复历史会创建新 commit。
• 新建需求必须选择一个 DSH 工作区；所有 AI 审核和评论分析 session 固定挂载该工作区，不会落入未分组 session。
• 支持默认 AI 上下文与工作区专属上下文合并，统一声明 Skill、MCP server、本地参考文档和 Agent Preset。

AI 上下文配置

插件通过 DSH profile 的 cordis.patch.yml 接收配置。defaultContext 会应用到全部工作区；workspaces 只为指定 workspaceId 追加资源，并可覆盖默认 agentPreset。未列入 workspaces 的已登记工作区仍可创建需求并继承默认上下文。

- id: spec-collab
  config:
    defaultContext:
      skills:
        - requirements-review
      mcpServers:
        - confluence
      documentPaths:
        - ~/company-docs/product-rules.md
      agentPreset: spec-review
    workspaces:
      - workspaceId: 00000000-0000-4000-8000-000000000001
        skills:
          - payment-domain
        mcpServers:
          - payments
        documentPaths:
          - docs/payment-rules.md
        agentPreset: spec-review-payments

新建需求窗口会读取 DSH 当前登记的全部工作区并要求选择。工作区专属 documentPaths 可写相对路径，AI 会基于所选工作区根目录读取；共享文档建议使用绝对路径或 ~。页面接口 GET /api/spec-collab/review-workspaces 返回可选工作区的 workspaceId、标题和路径，可用于填写覆盖配置。

升级前创建、尚未保存 workspaceId 的需求会显示“未绑定工作区”，其 AI 审核按钮保持禁用；通过“绑定工作区”补齐一次后即可继续。已绑定需求不允许切换工作区，避免同一需求的审核上下文中途变化。

Skill 和 MCP 必须已经由对应 Agent Preset 挂载：Skill 名称会要求 AI 先通过 skill 工具加载，MCP serverName 会映射为 mcp__<serverName>__* 工具 namespace。本插件不会在单次审核中安装外部代码或启动未授权 MCP；资源不可用时，AI 必须明确标记 TO_VERIFY，不能伪造 FACT。

绑定工作区会把 AI session 的当前目录设为该工作区的真实路径，但“挂载成功”不代表模型已经读取项目文件。默认工作区提示词会强制每次审核先检查根目录，读取存在的 AGENTS.md、CONTEXT.md、README.md、CONTRIBUTING.md 和项目清单，再按需求定位相关代码、文档、测试及 Git 历史。业务专属资料仍建议通过 documentPaths 明确指定。

AI 提示词配置

prompts 中每个字段都可以单独覆盖，未填写的字段继续使用插件当前内置提示词。动态的需求 ID、commit、审核类型和 session ID 由插件注入，不需要写进自定义提示词。

- id: spec-collab
  config:
    prompts:
      common: |-
        所有输出使用简体中文，并遵守团队的需求审核规范。
      productFirst: |-
        先检查用户目标、范围、业务规则和验收标准，再提交结构化审核结果。
      workspaceContext: |-
        ## 项目上下文
        项目：{{WORKSPACE_TITLE}}
        根目录：{{WORKSPACE_PATH}}
        审核前先读取项目规则、说明文档和相关实现。
        {{WORKSPACE_SNAPSHOT}}
        {{RESOURCE_INSTRUCTIONS}}
      resourceInstructions: |-
        可用 Skill：{{SKILLS}}
        可用 MCP：{{MCP_SERVERS}}
        指定文档：{{DOCUMENT_PATHS}}
      followUp: |-
        请基于当前审核上下文回答下面的追问：

        {{CONTENT}}

可配置字段：system、workspaceContext、resourceInstructions、common、productFirst、productSecond、engineeringPrecheck、changeReview、comment、followUp。

workspaceContext 必须各保留一次 {{WORKSPACE_SNAPSHOT}} 和 {{RESOURCE_INSTRUCTIONS}}，还支持 {{WORKSPACE_ID}}、{{WORKSPACE_TITLE}}、{{WORKSPACE_PATH}}。resourceInstructions 支持 {{RESOURCE_DETAILS}}、{{SKILLS}}、{{MCP_SERVERS}}、{{DOCUMENT_PATHS}}。followUp 必须保留且只能保留一个 {{CONTENT}}。未知变量和缺失的必需变量会在插件启动时直接报错，避免错误模板进入 AI 会话。完整默认值由包入口导出的 DEFAULT_REVIEW_PROMPTS 提供。

从源码安装（开发）

需要 Node.js 20+、pnpm 9+ 和可用的 DeepSeek Harness。

git clone https://github.com/zx490336534/dsh-spec-collab.git
cd dsh-spec-collab
pnpm install
pnpm run typecheck
pnpm test
pnpm run build
dsh plugin --profile web add "link:$(pwd)"

首次安装或 Host 代码变更后重启现有 dsh web。Client 开发时需在 DeepSeek Harness checkout 运行 pnpm run dev:web，插件侧运行 pnpm run bundle --watch，现有 GUI 的 client-plugin HMR 才会接收 bundle 更新。

键盘与响应式工作台

• Cmd/Ctrl+S：保存到版本库；缺少改动说明时会解释禁用原因。
• Cmd/Ctrl+Shift+F：进入或退出正文专注模式。
• 页签支持左右方向键与 Home/End；分栏支持方向键调宽，按住 Shift 加速。
• ≥1280px 使用三栏；960～1279px 收起需求导航；小于 960px 使用“需求列表 / 需求正文 / 协作”分段切换。

客户洞察导入

CSV 必填 body，可选 title、customer、company、external_ref、source、importance、captured_at 和 targets。Markdown 的每个二级标题对应一条洞察。单文件最大 5 MB、最多 2,000 条，提交前会展示新增、更新、重复和逐行错误，服务端以单个幂等动作原子提交。

下载 CSV 模板 · 查看 Markdown 模板

数据与迁移

~/.dsh/spec-collab/
  collaboration-v2.json       # 保留的 v0.2.x 原始数据，供回滚读取
  collaboration-v2.backup-<timestamp>.json
  collaboration-v3.json       # 协作、通知、洞察、统一指标和 AI 阶段会话
  repository/.git/            # 正式版本历史
  repository/requirements/
    <requirement-id>/spec.md

Git 是正式 Spec 版本的唯一事实源；协作账本不保存第二套 Markdown 历史。未正式保存的草稿只保存在当前浏览器 IndexedDB。

阅读 v3 迁移、回滚与隐私说明

安全与限制

• 默认仅允许 loopback + same-origin 浏览器请求。通过域名开放给团队前，需要在 DSH 前配置真实认证和可信反向代理策略。
• 花名用于协作归因，不是强身份认证；当前版本不提供 OAuth、组织、细粒度 ACL。
• 客户记录只保存显示名、公司名和外部编号，不保存邮箱、电话、凭证；重要度分不阻断 Ready。
• Markdown 禁用原始 HTML；正文最大 2 MB。
• AI review session 使用 DSH 既有 preset/sandbox 权限，不发送权限升级命令。
• 当前版本不实现 CRDT/OT、实时光标、附件上传和三方合并编辑器；并发保存使用 commit 冲突阻断。