人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载导读本文围绕 GSDspec-driven development扩展中 Auto 模式的**切片规划单元Plan Slice**展开深入剖析系统下发给执行 Agent 的 plan-slice 提示词模板它定义了切片规划这一 Agent 工作单元的使命、边界与 13 条硬性规划规则并强制通过 DB 支撑的gsd_plan_slice工具完成规划持久化。读完本文你将掌握该提示词模板的全部占位符与渲染机制、gsd_plan_slice工具从参数校验到事务写入的服务端行为、切片计划与任务计划的输出模板规范以及支撑这些约束的源码与测试证据从而能够理解甚至自定义 GSD Auto 模式的规划行为。一、plan-slice 在 GSD 工作流中的位置GSD Auto 模式把大型目标分解为里程碑Milestone→ 切片Slice→ 任务Task的层级结构每个层级对应一次独立的 Agent 单元执行。切片规划单元是整个执行链的关键一环Research调研→ Plan Slice切片规划→ Execute Task任务执行→ Slice Summary切片总结。plan-slice提示词正是切片规划单元下发给 Agent 的系统提示词。它是一份带占位符的模板文件位于 prompts 目录与research-milestone、plan-milestone、research-slice、execute-task等提示词并列同一目录下的plan-milestone.md、research-slice.md等模板共同组成 Auto 模式的完整提示词家族。从源码结构看该提示词由 auto-prompts.ts 中的buildPlanSlicePromptL2502构建最终调用内部函数renderSlicePromptL2325完成占位符替换与上下文注入。它面向的执行场景是Agent 已经拿到某个切片的 Research 结果、所在里程碑的 Roadmap 以及依赖切片的 Summary需要把这个切片要做什么落成一份可执行、可验证、可被后续任务执行器独立消费的切片计划与逐任务计划。二、提示词模板的占位符与渲染机制plan-slice.md本身是一份模板其中大量{{占位符}}由 prompt builder 在运行期替换。模板中出现的占位符及其含义如下占位符含义注入来源可从 auto-prompts.ts 中印证{{sliceId}}/{{sliceTitle}}/{{milestoneId}}单元标识buildPlanSlicePrompt的入参sid、sTitle、mid{{workingDirectory}}允许工作的目录worktree 根调用方传入的base参数{{inlinedContext}}预加载的项目/决策/需求上下文renderSlicePrompt内联的 roadmap 摘录、Slice Context、Slice Research、Decisions、Requirements、Knowledge、Graph 子图等{{dependencySummaries}}依赖切片的 SummaryForward IntelligenceinlineDependencySummaries先查 DB 中slice.depends回退到 Roadmap 解析{{sourceFilePaths}}相关源文件清单buildSourceFilePathsL346列出 PROJECT、REQUIREMENTS、DECISIONS、QUEUE、CONTEXT、ROADMAP、RESEARCH 等已知.gsd/产物{{executorContextConstraints}}执行器上下文窗口约束formatExecutorConstraintsL306基于执行器模型上下文窗口计算建议任务数与内联预算{{planTemplatePath}}/{{taskPlanTemplatePath}}输出模板路径配置的模板目录{{skillActivation}}技能激活指令默认文案要求 Agent 依据系统上下文中的GSD Skill Preferences与available_skills目录决定加载哪些技能{{commitInstruction}}提交指令由调用方注入外部状态模式下为不要提交.gsd/{{outputPath}}切片计划输出路径形如.gsd/milestones/M001/slices/S01/S01-PLAN.mdplan-slice-prompt.test.ts 对渲染机制做了严格验证所有占位符必须被替换assert.ok(!result.includes({{))、gsd_plan_slice等 DB 工具名必须在替换后依然存活、skillActivation占位符必须出现在所有领域提示词中且能被自定义文案替换。也就是说这份模板被设计为无残留占位符的最终交付提示词。三、Mission基于真实代码规划以 DB 为规范写入路径提示词的 Mission 段落定义了切片规划单元的核心任务——针对真实代码进行规划并通过 DB 支撑的工具持久化。原文的关键约束如下工具调用边界subagent只允许在planning-dispatch模式下用于隔离的规划侦察大范围子系统扫描、分解不清晰、需要外部事实外部研究必须派发scoutAgent禁止派发实现类 Agent。Roadmap 假设校验规划前必须用代码与依赖摘要校验 Roadmap 假设。若确有证据表明下游切片错误调用gsd_reassess_roadmap并携带sliceChanges.modified/sliceChanges.added/sliceChanges.removed否则保持 Roadmap 不变且默认偏向roadmap 是对的Bias toward roadmap is fine。已完成切片不可变更。源文件核实如果切片研究结果被内联可以信任其架构结论但任务inputs与expectedOutput中的每一个具体文件路径都必须对照当前目录树或先前/同任务输出核实。由于执行器后续只会拿到任务计划、切片摘录与先前摘要规划时必须把所有必要路径、步骤、输入输出写进任务计划。从实现层面看DB 是规范写入路径并非一句口号。plan-slice.ts 的handlePlanSliceL256在写入前执行完整的校验链validateParams必填字段与数组类型校验→ 仓库注册表校验targetRepositories必须声明过→ 路径作用域校验validatePlanningPathScope→ 预执行校验checkFilePathConsistencycheckTaskOrdering全部通过后才进入事务。工具执行器在 workflow-tool-executors.ts 中调用该 handler 并捕获错误。四、13 条规划规则逐条详解这是提示词的核心部分也是执行 Agent 必须遵守的行为准则。以下逐条展开并结合源码给出支撑证据。规则 1识别拥有的 Active 需求如果需求已预加载先区分本切片拥有的owned与支撑性的supportingActive 需求。这与需求上下文的内联机制呼应——renderSlicePrompt通过inlineRequirementsFromDb按 milestone/slice 作用域注入需求DB 不可用时回退到.gsd/REQUIREMENTS.md文件。规则 2调用 memory_query 检索记忆用切片标题与源文件中的关键词调用memory_query从项目记忆中召回相关历史经验。renderSlicePrompt也会通过inlineKnowledgeScoped按标题提取关键词内联知识条目二者共同保证规划不脱离项目既有认知。规则 3先读两份输出模板必须阅读{{planTemplatePath}}切片计划模板与{{taskPlanTemplatePath}}任务计划模板再动手规划确保输出结构与解析器预期一致。对应模板即 plan.md 与 task-plan.md详见本文第六节。规则 4技能激活与记录按{{skillActivation}}指令加载技能并在每个任务计划的skills_usedfrontmatter 中记录执行器应加载的技能。task-plan.md 的 frontmatter 明确包含skills_used列表字段。规则 5先定义切片验证在展开任务之前先定义切片的验证方式非平凡切片需要真实测试或可执行的断言边界契约需要契约演练检查测试不得读取.gitignore忽略的路径如.gsd/、.planning/、.audits/。这保证验证是可执行、可审计的而不是依赖 Agent 自述。规则 6按需覆盖质量门 Q3–Q7仅在适用处包含Threat SurfaceQ3、Requirement ImpactQ4、proof level、observability、integration closure、Failure ModesQ5、Load ProfileQ6与Negative TestsQ7。这组质量门Quality Gates被 plan-slice.ts 事务性地落库Q3、Q4 以 slice 作用域插入Q5、Q6、Q7 以 task 作用域为每个任务插入Q8 以 slice 作用域插入且与规划数据同事务——崩溃不会留下有门无任务的孤儿记录。模板 plan.md 中 Q3/Q4 对应 Threat Surface、Requirement Impact 小节task-plan.md 中 Q5/Q6/Q7 对应 Failure Modes、Load Profile、Negative Tests 小节。规则 7任务右尺寸化简单切片可以只有一个任务仅当上下文、所有权或验证边界确实需要拆分时才拆分。这防止一刀切拆任务带来的过度规划成本。规则 8verify 命令必须安全简单任务verify命令禁止使用 shell 管道、重定向、分号、反引号、命令替换、输出裁剪、grep 正则交替符|。如需多项检查创建一个小的测试文件并用node --test或包测试脚本运行多个简单命令只能用连接。这与 task-plan.md 的 Verify Rules 一致MUST be a mechanically executable command并由 pre-execution-checks.ts 中的validateVerificationCommand在预执行阶段把关。规则 9tasks[]的精确形状这是与工具契约最严格的一条。每个任务必须具有taskId、title、description、estimate、files、verify、inputs、expectedOutput以及可选的observabilityImpact。关键语义description应包含Why / Do / Done-when叙事files、inputs、expectedOutput必须是字符串数组即使只有一个路径也要写成inputs: [src/index.ts]绝不能写成inputs: src/index.ts所有路径相对{{workingDirectory}}不得出现工作目录之外的绝对路径expectedOutput只能列出任务实际创建或覆写的文件只读、只验证、只测试的文件只能进inputs纯验证/测试任务若无新文件产出expectedOutput可为[]或仅限测试结果产物磁盘上尚不存在但被当作input的文件必须由更早任务的expectedOutput产出——否则需要前置一个产出它的任务。该形状与 plan-slice.ts 中的PlanSliceTaskInput接口完全一致taskId/title/description/estimate必须非空字符串files/inputs/expectedOutput必须为字符串数组服务端validateTasksL88会在持久化前逐字段校验并拒绝非法载荷。规则 10用gsd_plan_slice持久化规划必须通过gsd_plan_slice提交milestoneId、sliceId、goal可选的successCriteria/proofLevel/integrationClosure/observabilityImpact以及tasks。工具事务化处理任务持久化并渲染{{outputPath}}与各任务计划不要调用gsd_plan_task也不要依赖直接写PLAN.md作为事实来源。这解释了 plan-slice.ts 中Guards DB writes inside a single transaction (prevents TOCTOU)的设计——守卫必须在事务内执行避免读取与写入之间状态被并发修改源码注释明确引用 issue #2723。规则 11结束前自审完成前自审目标/演示闭环、需求覆盖、已锁定的决策、具体路径、依赖顺序、接线、规模大小、证明真实性、功能完备性、质量门。非平凡切片/任务须包含适用的 Q3–Q7 覆盖。plan-slice-prompt.test.ts专门断言Self-audit before finishing文案在模板替换后依然存活。规则 12结构性决策落库若规划产生了结构性决策逐条调用gsd_decision_save工具持久化决策并重新生成.gsd/DECISIONS.md。提示词测试同样断言了这一点——渲染后的提示词包含gsd_decision_save且不再包含手工追加到.gsd/DECISIONS.md的旧式指令。规则 13提交指令按{{commitInstruction}}执行。在外部状态管理模式.gsd 由外部管理下注入的指令是不要提交规划产物测试 plan-slice-prompt.test.ts 中commitInstruction自定义文案可完整替换。其余约束还包括切片目录已存在、不要 mkdir自主执行——没有人类在场不得调用ask_user_questions或secure_env_collect应做合理假设并在文档中记录结尾必须调用gsd_plan_slice持久化规划状态并以固定句式Slice {{sliceId}} planned.收尾。五、服务端行为gsd_plan_slice的完整生命周期提示词末尾的MUST callgsd_plan_slice对应 plan-slice.ts 中的handlePlanSlice。理解服务端行为有助于把握提示词规则的为什么1. 校验链全部失败即拒绝不产生任何持久化副作用必填字段校验milestoneId、sliceId、goal必须非空tasks必须是非空数组每字段校验taskId必须唯一、title/description/estimate/verify非空、files/inputs/expectedOutput必须是字符串数组validateStringArray拒绝裸字符串仓库校验所有targetRepositories含 slice 级与 task 级必须出现在仓库注册表由.gsd/PREFERENCES.md加载中路径作用域校验files/inputs/expectedOutput中的绝对路径与相对穿越如../sibling-repo/...必须落在声明的目标仓库根内预执行校验文件路径一致性inputs必须存在于磁盘或由先前任务产出与任务排序禁止先读后产的序列违规。2. 事务内守卫与写入父里程碑必须存在且未关闭closed 状态下拒绝规划父切片必须存在且未完成已完成需先gsd_slice_reopen被本次规划省略的已完成任务不可删除cannot remove completed task若父切片处于deferred状态会自动恢复为pending使 Auto 模式可以重新派发它事务内写入 slice planning、逐任务 upsert、删除被省略的 pending 任务并同步种子 Q3/Q4slice 级、Q5/Q6/Q7task 级、Q8slice 级质量门行。3. 写入后渲染与钩子通过renderPlanFromDb从 DB 渲染切片计划与任务计划清除切片的 sketch 标志setSliceSketchFlag(..., false)使状态机从refining离开、进入可执行状态若渲染失败则保留 sketch 标志测试 plan-slice.test.ts 专门覆盖渲染失败但 DB 行保留用于调试的路径失效状态缓存与解析缓存重新渲染所有 projections、写入 manifest、追加事件日志cmd:plan-slice含 actor 与 trigger reason 审计字段。plan-slice.test.ts 用近 20 个集成测试覆盖了上述行为的绝大部分成功写入与渲染、显式/未知 targetRepositories、路径作用域与相对穿越拒绝、worktree 本地渲染、规划后状态机离开 planning/refining、sketch 标志清除与保留、省略 enrichment 字段时不渲染占位文案、非法载荷拒绝、裸字符串 IO 拒绝、外部绝对路径拒绝、缺失 input 拒绝、序列违规拒绝、缺失父切片拒绝、deferred 复活、幂等重跑、删除被省略的 pending 任务、拒绝删除已完成任务、以及validateStringArray导入回归PR #5872。这些测试同时是理解提示词规则 8/9/10 的最佳落地样例。六、输出模板切片计划与任务计划的结构规范提示词规则 3 要求规划前阅读两份模板因为它们定义了机器可解析的输出结构。plan.md切片计划包含Goal/Demo、Must-Haves、Threat SurfaceQ3、Requirement ImpactQ4、Proof Levelcontract/integration/operational/final-assembly含是否需要真实运行/人工 UAT、Verification先于任务定义的客观停止条件、Observability/Diagnostics运行时信号、检查面、失败可见性、脱敏约束、Integration Closure上游表面、本切片新增接线、里程碑端到端剩余工作、Tasks 清单与 Files Likely Touched。模板内嵌的格式规则值得注意复选框行严格形如- [ ] **T01: Title** \est:30m任务按 T01、T02…顺序执行verify必须是机械可执行命令禁止管道/重定向/分号/反引号/内联node -e内容类任务可验证文件存在性、章节数、YAML 有效性或字数如grep -q Required heading doc.md、test -s doc.md。task-plan.md任务计划以 frontmatter 开头estimated_steps与estimated_files供计划质量校验器检测 10 步骤或 12 文件的过程化任务并建议拆分、skills_used对应提示词规则 4。正文包含 Description、Failure ModesQ5依赖失败/超时/畸形响应的策略表、Load ProfileQ6共享资源、每操作成本、10x 断点、Negative TestsQ7畸形输入/错误路径/边界条件、Steps、Must-Haves、Verification、Verify Rules、Observability Impact仅运行时任务需要、Inputs 与 Expected Output——后者明确要求每个路径都用反引号包裹供机器解析推导任务依赖注释再次强调inputs/expectedOutput必须是字符串数组而非单个字符串。七、上下文注入、预算控制与失败重派renderSlicePrompt 在渲染模板前会按顺序内联前置块prependBlocks、Research 阶段交接锚点research-slicephase anchor、Roadmap 摘录摘录不可用时回退全文、Slice Context讨论产物、Slice Research、按切片标题推导作用域后的 Decisions 与 Requirementsminimal 级别跳过、Knowledge、Graph 子图。所有内联块都带有来源路径头并记录上下文遥测emitPromptContextTelemetry使提示词构建过程可观测。预算控制formatExecutorConstraintsL306根据执行器模型的上下文窗口resolveExecutorContextWindow支持context_window_override偏好issue #4435计算建议任务数范围taskCountRange与每个任务的字符预算注入{{executorContextConstraints}}指导 Agent 把任务控制在单一上下文窗口内可完成。这解释了提示词规则 7按上下文拆分任务的量化来源。失败重派buildPlanSlicePrompt支持priorPreExecFailure选项issue #4551当一次规划被预执行校验pre-execution-checks.ts拦截后重派提示词会追加Fix these specific issues段落列出阻塞引用并给出修复指引如把创建者任务提前、把只读文件从expectedOutput移除、修正 npm 包名避免 Agent 生成与上次完全相同、再次失败的规划。此外ADR-011 的渐进规划被中途关闭时softScopeHint会把先前捕获的 sketch 作用域作为非绑定软提示注入Treat it as context only而不是硬约束。八、测试证据与工程质量本主题由两层测试共同保障plan-slice-prompt.test.ts验证提示词模板本身占位符全部替换、DB 工具名gsd_plan_slice/gsd_plan_task/gsd_decision_save存活、canonical write path文案存活、规划中不手工写 DECISIONS语义、Q3–Q7 质量门文案存活、结尾必须指向gsd_plan_slice工具而非直接写文件、skillActivation占位符在全部 7 个领域提示词中一致存在。plan-slice.test.ts以真实临时工作区 SQLite DB 验证工具端到端行为覆盖前文第五节的全部守卫与渲染语义是提示词规则 → 服务端行为闭环的最直接证据。九、实践要点小结综合提示词、工具实现与测试使用 GSD Auto 模式的切片规划时值得记住的要点规划即数据切片计划的唯一事实来源是 DB任何绕过gsd_plan_slice直接写PLAN.md的行为都会被提示词明确禁止也会在重新渲染时被覆盖。输入输出语义严格分离inputs 已存在或先前任务产出的只读依赖expectedOutput 本任务实际写盘的文件。两者混用会触发预执行校验失败测试 plan-slice.test.ts 中missing input / sequence violation / later-task input三个用例演示了全部失败形态。验证优先于任务先定切片级验证与质量门Q3–Q7再细化任务验证命令保持机械可执行复杂断言放进node --test测试文件。尺寸适配上下文按执行器上下文窗口控制任务数与内联预算必要时拆分任务而非堆大任务。可观测与可恢复结构性决策用gsd_decision_save落库、切片的 observability 小节写明未来 Agent 如何检查失败状态这些都会随计划渲染进.gsd/milestones/…/slices/…/S01-PLAN.md等产物中成为下游执行器与总结单元的输入。如果你想进一步自定义这套规划行为可以从 prompts/plan-slice.md 模板本身、templates/plan.md 与 templates/task-plan.md 输出模板入手再配合 plan-slice-prompt.test.ts 调整对应断言——提示词、输出结构与测试构成了三位一体的可维护契约。赞分享人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载相关推荐OmO Prometheus 战略规划 Agent 深度解析薄提示词适配器与 ulw-plan 规划技能体系OmO Prometheus 战略规划 Agent 深度解析薄提示词适配器与 ulw plan 规划技能体系 Prometheus 是 oh my opena人工智能AI Agent代码智能体多智能体MCP ClientsAgent 编排深蓝词库转换项目实施计划模板解析基于 SpecKit 的 /speckit.plan 规划工作流深蓝词库转换项目实施计划模板解析基于 SpecKit 的 /speckit.plan 规划工作流 导读本文围绕深蓝词库转换imewlconverter开桌面应用CLI开发工具深度拆解 OpenCode 系统提示词CLI 编码 Agent 的规则体系、任务工作流与提示词工程范式深度拆解 OpenCode 系统提示词CLI 编码 Agent 的规则体系、任务工作流与提示词工程范式 OpenCode 是一款以终端为交互界面的软件工程编码文档知识库上一篇从零开始掌握Nuclei Templates网络安全扫描的终极武器下一篇AzurLaneAutoScript科研队列优化最大化经验获取的时间管理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考