前言¶
在 DSH 环境中开发多步骤任务时，会话中断或上下文压缩容易导致进度丢失。为了解决这个问题，需要一种将规划、状态和复盘记录持久化到磁盘的机制。
插件介绍¶
trailmap（轨迹地图）是一个工作流插件，由 JohnXu22786 维护。它将任务的所有信息存储在工作区的 .trail/ 目录中。无论会话如何中断，都可以通过读取状态继续工作。
核心功能¶
- 状态机驱动：步骤状态在
todo、in progress和done之间流转，支持取消和恢复。依赖未满足时步骤自动标记为“blocked”。 - 计划模板生成器：根据任务类型（research/development/docs/blank）一键生成里程碑骨架，依赖关系自动 wiring。
- 依赖标注：步骤可声明依赖，启动步骤前校验依赖，自动检测循环依赖。
- 审计事件流：所有进展写入追加日志，复盘时自动引用。
- 复盘纪要：任务结束时自动汇总里程碑、步骤、取消情况和时间线，支持手动编写复盘部分。
- 确定性完成门：
check命令验证所有步骤关闭且结构正确。 - 三种接口：提供 dsh 工具（10 个
trailmap_*）、独立 CLI（trail）和技能（SKILL.md）。
安装与启用¶
安装前请确保环境满足 Node >= 20。使用官方安装命令：
dsh plugin --profile demo add github:JohnXu22786/file-planning
插件会通过 cordis.patch.yml 注入配置，并将工具注册到 ctx.tools，模型可调用 trailmap_* 工具。
典型用法¶
使用 CLI 进行初始化、流转和复盘：
# 1. 初始化计划（使用 blank 类型以运行完整循环）
node bin/trail.js init "Add regression tests to the toolchain" --kind blank
# 2. 查看状态
node bin/trail.js status
# 3. 启动第一个里程碑
node bin/trail.js start m1-1
# 4. 执行工作...
# 5. 完成步骤
node bin/trail.js finish m1-1
# 6. 完成门检查（步骤关闭且结构正确时通过）
node bin/trail.js check
# 7. 复盘并归档
node bin/trail.js debrief --close
也可以通过 npm link 后直接使用 trail 命令。
注意事项¶
- 目录权限：插件以当前 DSH 进程权限运行，请确保有权限读取和写入
.trail/目录。 - 版本控制：
.trail/目录默认排除在版本控制之外，建议手动检查.gitignore。 - 依赖：依赖
@deepseek-ai/cordis和@deepseek-ai/dsh-tools。 - 代码审查：安装前请检查源码与许可证（MIT）。
