Files

FNS Service 682e3e52df Update from Sync Service

2026-06-22 11:30:51 +08:00

6.9 KiB

Executable File

Raw Permalink Blame History

GSD Core - AI 编码上下文工程与规范驱动开发框架

GitHub: https://github.com/open-gsd/gsd-core npm: @opengsd/gsd-core License: MIT Slogan: Git. Ship. Done. 研究日期: 2026-06-07

一句话总结

GSD Core 是一套上下文工程（Context Engineering）+ 规范驱动开发框架，通过全新上下文子代理（fresh-context subagent） 架构解决 AI 编码中「上下文腐化」问题，让 Claude Code、Cursor、Codex 等 AI 编程工具在大型项目中保持高质量输出。

解决的核心问题：上下文腐化（Context Rot）

AI 编码会话随着对话轮次增加，上下文窗口逐渐被填满。模型不会报错，但输出质量静默下降：

开始 contradicts 早期决策
代码风格偏离初始约定
计划忽略早期明确的需求
臆造之前正确记忆的文件名/函数签名

这不是 bug，是 Transformer 注意力机制在长序列上的固有特性——信噪比随窗口填充而劣化。

核心方案：全新上下文子代理

核心洞察：编码会话中大部分工作（研究、规划、编写、验证）不需要在主上下文中进行。

架构设计：

主会话（编排器）：不碰源文件，只负责派发代理、收集结果、更新状态。上下文缓慢增长。
子代理：每个子代理以干净 200k token 上下文启动，只接收当前任务所需上下文，完成后终止。

主会话（轻量编排器）
  ├── Researcher Agent (200k fresh context)
  ├── Planner Agent (200k fresh context)  
  ├── Plan-Checker Agent (200k fresh context)
  ├── Executor Agent × N (200k fresh context, 并行)
  └── Verifier Agent (200k fresh context)

5阶段循环（Phase Loop）

每个里程碑通过重复的 5 步循环推进：

Discuss → [UI Design] → Plan → Execute → Verify → Ship

1. Discuss（讨论）

在规划前捕获实现决策（用什么库、错误处理策略、边界情况）
输出 CONTEXT.md（结构化决策记录）
几分钟对话避免几小时返工

2. UI Design（可选）

视觉相关阶段可选 /gsd-ui-phase
输出 UI-SPEC.md（布局、交互、视觉行为的设计契约）

3. Plan（规划）

3个全新上下文子代理依次运行：
- Researcher → 调研生态，输出 RESEARCH.md
- Planner → 读研究+CONTEXT，输出 PLAN.md
- Plan-Checker → 验证计划完整、一致、在范围内
计划按依赖波次排列，支持并行执行

4. Execute（执行）

每个 Executor 以 200k 干净上下文启动
只加载：项目摘要 + 阶段上下文 + 研究 + 具体 PLAN.md
原子提交，每 commit 对应一个计划任务
按波次并行，前波完成后启动后波

5. Verify（验证）

不只是测试，检查：
- 需求覆盖率（REQ-ID 是否都处理了）
- 决策覆盖率（CONTEXT.md 的决策是否落地了）
- 整体阶段目标对齐
输出 VERIFICATION.md + 修复计划（如有偏差）

6. Ship（交付）

创建 PR，归档阶段产物
更新 STATE.md 标记阶段完成
开始下一个阶段循环

关键文件结构

.planning/
├── STATE.md           # 项目当前状态（里程碑/阶段/进度）——系统脊梁
├── phases/
│   ├── CONTEXT.md     # 讨论阶段的实现决策
│   ├── RESEARCH.md    # 调研发现
│   ├── PLAN.md        # 具体执行计划（按波次）
│   ├── UI-SPEC.md     # UI 设计契约（可选）
│   └── VERIFICATION.md # 验证报告
ROADMAP.md             # 项目路线图

支持平台

Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf 等。

快速开始

npx @opengsd/gsd-core@latest
# 选择运行时和安装方式
/gsd-new-project

也提供轻量模式：

/gsd-quick — 不需要完整阶段循环的快速任务
/gsd-fast — 更轻量的即时操作

三大支柱

Fresh-context subagents — 每个子代理干净启动，结构性地解决上下文腐化
Spec-driven development — 执行前产出结构化产物（CONTEXT/RESEARCH/PLAN/VERIFICATION），代理精确执行
Meta-prompting — 代理定义本身是精心工程化的 prompt，编码了领域知识

与 Trellis 对比

维度	GSD Core	Trellis
核心理念	上下文工程 + 子代理架构	规范持久化 + 记忆
解决痛点	上下文腐化（质量随窗口填充下降）	AI 每次从零开始（无记忆）
架构	主会话编排 + fresh-context subagents	4阶段循环（Plan→Implement→Verify→Finish）
记忆机制	文件系统（.planning/ 目录）	.trellis/workspace/ journal
平台支持	10+ 平台	14+ 平台
License	MIT	AGPL-3.0
适用规模	中大型复杂项目（上下文腐化严重时收益最大）	个人/团队通用
轻量模式	/gsd-quick, /gsd-fast	无
验证深度	需求+决策+目标三重验证	lint+type-check+测试

评价

✅ 优点

深刻理解了 AI 编码的根本问题（上下文腐化是 Transformer 固有特性，不是 workaround 能解决的）
fresh-context subagent 是结构性解决方案，不是权宜之计
5阶段循环设计严谨，每步都有明确存在的理由
验证环节不仅是测试，而是需求+决策+目标三重覆盖
MIT 许可证友好
诚实承认 trade-off（简单任务不需要用完整循环）

⚠️ 注意

对简单任务有流程开销（官方也承认）
子代理启动延迟比单会话编辑慢
需要一定学习曲线理解阶段循环概念
最适合中大型复杂项目，小项目用 /gsd-quick 即可

📊 项目成熟度

完整文档体系（教程/指南/参考/概念）
CI/CD 测试覆盖
活跃的社区（Discord + 多语言 README）
多平台支持
有 CLI 工具和完整命令体系

核心洞察（值得记住）

"The model is not forgetting — it never 'remembered' in the human sense. It is weighting relevance across a finite window, and as that window fills with accumulated noise, signal-to-noise degrades."

"An executor that runs with 180k tokens of accumulated session history is a degraded executor. An executor that starts clean and reads only what its plan requires is an executor operating at full capacity."

6.9 KiB Executable File Raw Permalink Blame History Unescape Escape