file-planning

English

trailmap（轨迹地图）

磁盘持久化的执行规划插件：把多步骤任务的计划、执行状态、考察笔记与复盘纪要 全部落在工作区 .trail/ 目录里。会话中断、上下文压缩、换会话重启都不丢方向—— 恢复后读一眼状态即可继续。

• 状态机驱动：步骤 待办 → 进行中 → 完成（可取消/复活），依赖未满足的 步骤自动标记为「受阻」；里程碑与计划状态由步骤派生，无需手工维护。
• 计划模板生成器：按任务类型（调研/开发/文档/空白）一键生成里程碑骨架， 自动接好步骤依赖，创建后仍可随时增删改。
• 依赖标注：步骤可声明依赖，start 受依赖门控；循环依赖会被检测并阻断。
• 审计事件流：每次推进都写入追加式事件记录，复盘自动引用，过程可追溯。
• 复盘纪要：收尾时自动汇总里程碑/步骤/取消项/时间线，手写回顾区跨次生成 保留。
• 确定性收尾闸门：check 判定全部步骤闭合且结构无问题，避免"以为做完了"。
• 三种接口：dsh 工具（10 个 trailmap_*）、独立 CLI（trail）、技能 （SKILL.md），共享同一核心。

快速开始（CLI，零依赖）

node bin/trail.js init "为工具链添加回归测试" --kind blank
node bin/trail.js status
node bin/trail.js start m1-1
# ……执行工作……
node bin/trail.js finish m1-1
node bin/trail.js check        # 收尾闸门（步骤闭合后通过）
node bin/trail.js debrief --close   # 复盘 + 归档

（--kind blank 只有一个步骤，便于把建轨迹→推进→收尾全流程跑通；--kind build 会生成完整里程碑骨架，见命令速查与 docs/format.md。）

（或 npm link 后直接使用 trail 命令；TRAILMAP_DIR 环境变量指定工作区， 缺省为当前目录。）

在 DSH 中安装

dsh plugin --profile demo add github:JohnXu22786/file-planning

接入 dsh（插件化 harness）

dsh plugin --profile demo add ./file-planning
dsh --profile demo --dump-config   # 应出现 dsh-plugin-trailmap 补丁层
dsh --profile demo

harness 通过 cordis.patch.yml 插入插件行，Cordis 注入 ctx.tools 并注册全部 工具；模型即可调用 trailmap_* 完成建计划/推进/复盘全流程。技能放在 skill/trailmap/。详见 docs/integration.md。

工作区文件

<工作区>/.trail/
├── map.json          # 唯一事实源（计划 + 状态 + 审计事件）
├── map.md            # 渲染视图：状态行 / 下一步 / 勾选清单
├── fieldnotes.md     # 考察笔记
├── journal.md        # 行程日志
├── debrief.md        # 复盘纪要
├── .active           # 活动计划指针（多计划）
└── plans/<别名>/     # 平行计划

.trail/ 默认不纳入版本控制。文件格式与状态机详见 docs/format.md。

命令速查

命令	作用
trail init <目标> [--kind …] [--name 别名]	建轨迹（模板骨架 + 依赖接线）
trail status [--history] [--json]	状态总览
trail start/finish/drop/reopen <步骤ID>	步骤状态机（drop 需 --reason）
trail amend …	中途修正计划结构
trail note <文本> [--section 小节]	考察笔记
trail journal <文本>	行程日志
trail check [--json]	完成判定闸门（未通过时退出码 1；--json 模式退出码恒 0，以 ok 字段为准）
trail debrief [--close] / trail close	复盘（+归档）
trail render	手工编辑 map.json 后重生成视图
trail plans / switch <别名> / switch root	多计划管理

开发

node --test          # 全部单元测试（node 内置测试运行器，零依赖）

• lib/machine.js：纯状态机（转移/派生/校验/循环检测）
• lib/ops.js：操作层（CLI 与 dsh adapter 共用）
• adapter/index.js：dsh 工具插件入口
• scripts/adapter-smoke.mjs：对真实 @deepseek-ai/dsh-tools 的冒烟验证。 运行方式：新建临时目录，npm init -y && npm pkg set type=module， npm i @deepseek-ai/dsh-tools @deepseek-ai/cordis，把本脚本复制到临时目录根， 并把 lib/、adapter/ 两个目录也复制过去，执行 node adapter-smoke.mjs

目录结构

file-planning/
├── adapter/            # dsh 插件入口（Cordis plugin）
├── lib/                # 核心库（零依赖）：machine/store/render/templates/ops/cli
├── bin/trail.js        # CLI 入口
├── skill/trailmap/     # 技能（SKILL.md）
├── scripts/            # 冒烟验证脚本
├── test/               # 单元测试（node --test）
├── docs/               # 接入说明 / 文件格式约定
├── examples/           # 示例工作区（完整执行完毕的轨迹）
├── cordis.patch.yml    # bundle 补丁层
└── package.json        # bundle 清单（dsh.bundle）

许可

MIT，见 LICENSE。