Files

FNS Service 682e3e52df Update from Sync Service

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

6.9 KiB

Executable File

Raw 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 Blame History Unescape Escape