📦 @goodandready/dsh-time-machine

⚡ 插件概览

dsh-time-machine 为 DeepSeek Harness 智能体提供全自动工作区安全护栏与即时状态回滚引擎。

智能体在执行多文件批量重构、依赖安装或高危终端命令时，一旦发生代码损坏或逻辑回归，手动 Git 回退不仅繁琐，还容易丢失未跟踪的新建文件。

本插件在后台利用影子 Git 快照技术（Shadow Git Snapshots）自动捕获工作区状态，不污染用户 Git 提交树与分支，支持一键即时回退、可视化文件 Diff 对比以及命令失败时的主动自愈挽救。

graph LR
    subgraph AgentAction [智能体执行操作]
        Agent[🤖 智能体: 批量修改文件 / 执行终端命令] --> Trigger{执行前置拦截}
    end

    subgraph TimeMachine [dsh-time-machine 引擎核心]
        Trigger --> ShadowGit[影子 Git 快照引擎]
        ShadowGit --> Snapshots[(时序检查点历史队列)]
        Snapshots --> DiffEngine[可视化工作区 Diff 计算器]
    end

    subgraph SafetyNet [安全防护与界面集成]
        DiffEngine --> Sidebar[🕒 侧边栏 Time Machine 时间轴]
        Snapshots --> Rollback[⏪ 一键毫秒级即时回滚]
        Rollback --> CleanState[恢复纯净安全状态]
        Trigger -.->|命令报错| AutoHeal[🩹 自动弹出回滚修复建议]
    end

    style AgentAction fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
    style TimeMachine fill:#181825,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4
    style SafetyNet fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4

🛠️ 智能体工具列表 (6 个工具)

📦 安装指南

dsh plugin --profile web add @goodandready/dsh-time-machine

⚙️ 配置说明 (settings.yaml)

dsh-time-machine:
  autoSnapshotEnabled: true    # 文件修改前自动创建快照
  maxSnapshots: 20             # 内存保留的最大滚动检查点数量
  autoHealPrompt: true         # 终端命令执行失败时提示回滚

📋 版本更新记录 (Release Notes)

v0.1.10 — 稳定性、动态工作目录、统一 Diff 与架构优化

• Added in v0.1.10: 动态工作区感知（cwd）：时光机工具与 REST 接口自动关联当前会话目录或支持显式工作区路径。
• Added in v0.1.10: 统一补丁支持（format: "patch" | "stat"），带输出截断保护（最大 256KB）。
• Added in v0.1.10: Git 变动操作异步排队队列，彻底解决高并发下的 index.lock 竞争冲突。
• Added in v0.1.10: 采用 git for-each-ref 批量查询引用，消除 $O(N)$ 次 git log 进程生成，极大加速快照加载。
• Added in v0.1.10: 空提交去重：若工作树无变化，自动跳过重复快照创建。
• Added in v0.1.10: 启动时自动清理遗留的 tm_index_* 临时暂存索引文件。
• Changed in v0.1.10: 精简设置卡片界面，引导在侧边栏时光机标签页查看时间线。
• Changed in v0.1.10: 完善错误告警日志（console.warn），替换静默吞并异常。

v0.1.9 — 事件总线统一与依赖清理

• Changed in v0.1.9: 统一事件总线监听逻辑，杜绝自动快照重复触发。优先使用原生 DSH session/event 总线，仅在缺失 ctx.on 时启用 legacy ctx.events 回退。
• Changed in v0.1.9: 从 peerDependencies 中移除未使用的 @deepseek-ai/dsh-credentials。
• Added in v0.1.9: 新增项目设计规范文档 docs/design/DESIGN.md。

v0.1.7 — 分支历史安全、暂存区隔离与 DSH 原生事件总线

• Changed in v0.1.7: 安全工作区回滚。改用 read-tree + checkout-index + clean -fd，彻底杜绝回滚时误将分支 HEAD 覆盖为孤立提交的严重缺陷。
• Changed in v0.1.7: 保护用户 Git 暂存区。快照操作通过独立的 GIT_INDEX_FILE 执行，不会覆盖 .git/index 中已暂存的文件。
• Changed in v0.1.7: 原生对接 DSH session/event 事件总线，全面激活 turn/start、approval/asked、turn/end 和错误自愈事件监听。
• Changed in v0.1.7: 修复快照淘汰时的 Git 引用泄露问题，自动执行 git update-ref -d。
• Changed in v0.1.7: 修复 Diff 计算，直接对比当前工作区中的未提交修改。
• Changed in v0.1.7: 严格遵循 DSH 插件规范：仅在 ready 状态下允许编辑配置。
• Added in v0.1.7: WebServer API 增加 1MB 请求体大小上限，抵御 DoS 攻击。
• Added in v0.1.7: 前端界面完整支持中文本地化 (zh)。

📄 开源协议

MIT © GooDAnDReaDY