分阶段计划执行 xiaxi626/staged-plan-execution

staged-plan-execution

一个 Trae 技能，把任何多步骤的修复/改进计划包装成完整、智能体可执行的提示词——内置质量门禁、原子提交、CHANGELOG 规则和多会话交接。

中文文档

它能做什么

给它一份这样的多步骤计划：

Step 1: add lock to foo
File: src/foo.ts
Change: import withManifestLock, wrap function body
...
Step 2: desensitize bar error
...
| Step | Content | Files |
| 1 | lock foo | src/foo.ts |
| 2 | desensitize bar | src/bar.ts |
After each step: npm run typecheck && npm run lint && npm test

它会生成一份完整的提示词，像这样：

You need to execute the following revision plan for the current project,
completing each step in order. Run quality gates after each step before
proceeding to the next.

Project style requirements (all steps)
(Points at the source files the plan touches + sibling test files as style examples)

Atomic commit rules (strict)
(fix + docs commit split rules)

CHANGELOG rules (strict)
(location, revision, date rules)

README update rules
(conditional logic)

Context management and stage handoff
(four-backtick handoff prompt — 7 mandatory sections + skeleton)

<plan title>
(plan body preserved verbatim, project name → "current project",
code-block identifiers untouched)

After all steps complete
(final verification checklist)

生成的提示词专为多会话接力执行设计：每完成一步，执行智能体输出一份交接提示词（用四个反引号包裹），你复制到新会话里继续。

为什么需要它

跨多个智能体会话执行多步骤计划时，有三个问题反复出现：

1. 上下文漂移——后面的会话忘了前面会话定下的约定
2. 交接格式不统一——每个会话都自创一套「我做到哪了」的格式
3. 风格回退——上下文一紧张，智能体就跳过质量门禁，或者把代码和文档混进同一个提交

这个技能把约定固化进模板驱动的生成器，让每次交接都原样携带完整的执行框架。

结构

.trae/skills/staged-plan-execution/
├── SKILL.md # Entry: purpose, scope, generation rules, reference table
├── references/ # Hard constraints, loaded verbatim into generated prompt
│ ├── project-style-guide.md # 6 style rules + ecosystem identification + file-pointing
│ ├── atomic-commit-rules.md # fix + docs commit split + build artifact scope
│ ├── changelog-rules.md # Keep a Changelog conventions
│ ├── readme-rules.md # Conditional README update logic
│ ├── handoff-format.md # 7 mandatory handoff prompt sections + skeleton
│ └── final-verification.md # Post-completion verification checklist
├── templates/
│ └── plan-prompt-template.md # Overall skeleton of the generated prompt + placeholder rules
└── examples/
└── sample-plan-to-prompt.md # 实战示例：计划输入 → 生成的提示词

这样拆分是有意为之：

- SKILL.md 保持精简 —— 加载快，让智能体迅速判断要不要调用这个技能
- references/ 存放重量级约束 —— 按需加载，然后原样复制进生成的提示词。这样能保证可复现：同一份计划永远产出同一份提示词，不受智能体记忆影响
- templates/ 定义拼装顺序 —— 智能体不用自己发挥结构
- examples/ 锚定理解 —— 具体展示输入 → 输出的形态

适用范围

默认假设使用这套技术栈和这些约定：

- 语言：TypeScript / npm（npm run typecheck / lint / test / build）
- 测试：node:test + tsx，测试文件命名为 xxx.test.ts，临时目录隔离
- CHANGELOG：Keep a Changelog 风格（## [Unreleased]）
- 执行模型：多会话接力 —— 每一步都以四反引号交接提示词收尾

这个技能针对 DeepSeek harness 插件生态调优（双语 CONTRIBUTING、src/ + test/ + lib/ 目录结构、dsh- 命令行前缀）。用在其他 TS/npm 项目上照样能跑；非 TS 项目则需要改写 references/。

关键设计取舍

| 取舍 | 理由 |
| 计划内容原样保留 | 计划作者的意图不能被转述或概括 |
| 项目名 → 「当前项目」 | 让技能与任何具体仓库解耦 |
| 代码块标识符保持原样 | 它们属于代码，不是正文 |
| 智能体必须在生成时读取 references/ | 防止记忆漂移；同一份计划 → 每次都是同一份提示词 |
| 智能体扫描计划，定位到具体文件 | 恢复计划与提示词的紧密度 —— 风格指南一节会点名计划涉及的准确文件及其同级测试文件 |
| 四反引号交接包装 | 让内层的三反引号代码块在用户复制交接内容时完整存活 |

怎么用

作为 Trae SKILL

1. 把 staged-plan-execution/ 目录放到工作区的 .trae/skills/ 下
2. 给智能体一份多步计划
3. 智能体识别出这个技能，读取 references/ 和 templates/，然后在对话里输出完整提示词
4. 把生成的提示词复制到全新的智能体会话里，开始执行

作为其他工具的参考

references/ 和 templates/ 都是纯 Markdown。你可以把它们改写成其他智能体框架、CI 流水线或文档生成器的提示词 —— 这些约定本身与工具无关。

局限

- 以 TS/npm 为中心：references/ 用了 JS 专有术语（JSDoc、after() 钩子、lib/ 构建产物）。换 Python/Go/Rust 就得改写风格指南
- 一次调用只处理一份计划：不会把多份计划合成一份提示词
- 不做计划校验：不检查计划是否合理 —— 用户给什么就包装什么

License

MIT