xchannel1987/dsh-sdd-progress-xc

中文 | English

DSH SDD 进度插件 —— 在右侧边栏展示当前会话的 Subagent-Driven Development 任务进度（todos）和进度台账（progress.md），支持实时刷新和 Markdown 渲染。

宿主要求：DSH ≥ 0.2.0-rc.1（engines.dsh）。0.2.0 起 @deepseek-ai/dsh-client-runtime 已从宿主移除。

✨ 核心特性

📋 任务进度（Tasks Tab）

• 实时统计：显示已完成 / 进行中 / 待办任务数量
• 状态图标：✓ 完成 / ⏳ 进行中 / ○ 待办，一目了然
• 自动刷新：5 秒轮询，任务状态变化即时反映
• 会话绑定：自动关联当前会话的 todo 数据

📖 进度台账（Progress Ledger Tab）

• Markdown 渲染：使用 DSH 官方 MarkdownText 组件，支持 GFM / KaTeX 数学 / 代码高亮 / 代码复制
• 自动定位：从会话内容提取 sdd/progress.md 路径，无需手动配置
• 根目录无关：支持任意目录结构（如 /projects/foo/aiAssistant/sdd/progress.md）
• 安全渲染：禁用 raw HTML / 相对链接 / 危险协议，防止 XSS

🔄 实时刷新

• 页头刷新按钮：Tasks 和 Ledger 共用，一次刷新全部数据
• 自动轮询：5 秒间隔，无需手动操作
• 手动兜底：点击刷新按钮立即生效

🎯 会话绑定

• 自动识别：通过会话内容中的路径引用定位需求目录
• 多需求支持：同一 DSH 实例可同时查看不同需求的进度
• 会话切换：切换会话时自动加载对应进度

📝 Markdown 渲染

• 官方组件：使用 @deepseek-ai/dsh-client-ui-primitives 的 MarkdownText
• 完整能力：GFM 语法 / KaTeX 数学公式 / 代码高亮 + 复制按钮 / 脚注
• 流式优化：增量解析，冻结已稳定块，仅重解析尾部
• 安全沙箱：面向不可信内容的渲染器，自动处理 XSS

🔧 工作原理

用户打开 SDD Progress tab
    ↓
客户端请求 /api/dsh-sdd-progress-xc/progress?sessionId=...
    ↓
服务端读取 session.v3.jsonl.zstd（多帧 zstd）
    ↓
解析会话内容：
  - 提取 cwd + sessionId
  - 提取最新 todo/write 事件
  - 扫描路径引用，匹配 sdd/progress.md
    ↓
返回 { requirementName, todos, ledger }
    ↓
客户端渲染：
  - Tasks tab：统计 + 任务列表
  - Ledger tab：MarkdownText 渲染台账

zstd 多帧解码：DSH 会话日志是多帧 zstd 拼接，单帧 zstdDecompressSync 只解码首帧。插件实现 scanZstdFrames 扫描帧边界，逐帧解码拼接，完整还原会话内容。

需求名提取：正则匹配会话内容中的 ((?:盘符)?任意根/<name>/sdd/progress.md) 路径，提取 <name> 作为需求名。支持 Windows 路径（D:\\workspace\\requirements\\aiAssistant\\sdd\\progress.md）和 Unix 路径（/projects/foo/aiAssistant/sdd/progress.md）。

📦 安装

# 使用 DSH CLI
dsh plugin --profile web add dsh-sdd-progress-xc

# 或使用 npm
npm install dsh-sdd-progress-xc

安装后重启 DSH，右侧边栏将出现「SDD Progress」tab。

⚙️ 配置

选项	默认值	说明
requirementsRoot	''（空）	可选：当会话内容只有相对路径时，作为根目录兜底。通常无需设置

为什么默认不需要配置？
插件从会话内容直接提取完整路径（如 D:/workspace/requirements/aiAssistant/sdd/progress.md），不依赖固定根目录。只要会话中引用过该路径，就能自动定位。

🎮 使用

查看任务进度

1. 打开右侧边栏
2. 点击「SDD Progress」tab
3. 默认显示「Tasks」tab：统计 + 任务列表
4. 点击「Progress Ledger」tab 查看台账

刷新数据

• 自动：5 秒轮询，无需操作
• 手动：点击页头右侧「↻ Refresh」按钮

切换会话

• 切换到其他会话时，SDD Progress 自动加载该会话的进度
• 每个会话独立，互不干扰

🔒 安全设计

• Markdown 渲染：使用官方 MarkdownText，禁用 raw HTML / 相对链接 / 危险协议
• 路径提取：仅从会话内容提取路径，不扫描文件系统
• zstd 解码：逐帧解码，跳过损坏帧，不崩溃
• 会话隔离：每个会话独立，不跨会话污染

📄 许可证

MIT

🔗 链接

• GitHub
• npm
• 问题反馈
• DSH 官方仓库