@geminix/gxpm 0.1.0

package/docs/research/perplexity-agent-skills-design.md

@@ -0,0 +1,168 @@
+# Perplexity 团队内部 Agent Skills 设计、迭代与维护之道
+
+> **作者：** meng shao (@shao__meng)  
+> **来源：** https://x.com/shao__meng/status/2053098123074105705  
+> **发布时间：** 2026-05-09 06:01  
+> **互动数据：** 4 回复, 24 转发, 143 点赞, 162 收藏, 13.2K 浏览
+
+---
+
+Perplexity Agents 团队的内部规范公开版，核心论点很反直觉：
+
+> **写 Skill 不是写代码，而是为模型构建上下文。**  
+> 把工程师写代码的本能直接套到 Skill 上，几乎一定会失败。
+
+原文链接：https://research.perplexity.ai/articles/designing-refining-and-maintaining-agent-skills-at-perplexity
+
+---
+
+## Skill ≠ 代码，以 Python 信条和 Skill 反信条为例
+
+| Python 信条 | Skill 反信条 |
+|------------|-------------|
+| Simple is better than complex | **Skill 是文件夹，复杂性是特性** |
+| Explicit is better than implicit | **激活靠隐式模式匹配 + 渐进披露** |
+| Sparse is better than dense | **每 token 都要榨出最大信号** |
+| 特例不应破坏规则 | **Gotchas 才是最高价值内容** |
+| 容易解释的实现是好实现 | **容易解释的，模型已经会了 → 删掉** |
+
+---
+
+## Skill 的四重定义
+
+### 1. Skill 是目录（不是单文件）
+
+- **标准结构：** `SKILL.md` + `scripts/` + `references/` + `assets/` + `config.json`
+- **复杂领域用多级层次**
+  - 例：美国税法有 1945 个 IRC 条款，扁平加载比不加载效果更差；分三级嵌套后才可用
+  - 但层次本身有代价，需要导航工具（quick reference、自定义检索）来对冲间接性
+
+### 2. Skill 是格式
+
+- **frontmatter 必须有：**
+  - `name`（小写、连字符、与目录同名）
+  - `description`
+- **description 是路由触发器，不是文档**
+  - ❌ 常见错误：`「This Skill does X」`
+  - ✅ 正确写法：`「Load when …」`
+- **`depends:`** 用于级联依赖；运行时元数据可用辅助 JSON/YAML 隔离，避免污染上下文
+
+### 3. Skill 是可调用的
+
+**加载流程：**
+```
+load_skill() → 拷贝目录入沙箱 → 递归装依赖 → 剥离 frontmatter，仅暴露 body 与附属文件
+```
+
+### 4. Skill 是渐进式的（这是最重要的成本模型）
+
+| 层级 | 内容 | 大小 | 生命周期 |
+|------|------|------|----------|
+| **Index** | 所有 Skill 的 name+description | ~100 tokens/Skill | 每次会话、每个用户、**永远** |
+| **Load** | SKILL.md body | ~5,000 tokens | 一次加载，会话内持续占用 |
+| **Runtime** | scripts / references / 子 Skill | 无上界 | 仅模型实际读取时 |
+
+> **→ 越靠上的层，每个字越贵。**  
+> **Index 是「奢侈品柜台」，Runtime 是「无限仓库」。**
+
+---
+
+## 什么时候不需要 Skill
+
+反复强调 **「Every Skill is a tax」**。三类典型滥用：
+
+1. **模型已会的** — 写一串 git 命令 → 是好文档，是坏 Skill
+2. **重复 system prompt 的** — 通用知识应进全局上下文，不该走条件加载
+3. **变化太快的** — 远端 MCP 工具版本频繁变 → Skill 会漂移导致幻觉
+
+**判断单句是否该留的尺子：**
+> 「没有这句话，Agent 会做错吗？」  
+> 答否即删。
+
+引用 Pascal：
+> 「这封信写得长，是因为我没时间写短。」
+
+—— 写短 Skill 很难；写得快的 Skill 大概率有问题。
+
+还引了一篇研究：**LLM 自生成的 Skill 平均无收益**，因为模型无法可靠地把"自己消费有用的程序性知识"写出来。
+
+---
+
+## 构建五步法（顺序不可调）
+
+### Step 0 — 先写 Evals
+
+- 源自真实查询、已知失败、邻域混淆
+- **负例往往比正例更重要**
+
+### Step 1 — 写 Description（最难的一行）
+
+- 以 `"Load when…"` 开头，≤ 50 词
+- 描述用户意图（用真实抱怨语：`「babysit」` `「watch CI」` `「make sure this lands」`）
+- **不要总结工作流**
+- **唯一目标：** 路由准确，最小化对其他 Skill 的回归影响
+
+### Step 2 — 写 Body
+
+- **跳过显然的**
+- **不要罗列命令序列**
+- **用意图陈述代替过程脚本**
+
+❌ 反面示例：
+```
+git log; git checkout main; git checkout -b; git cherry-pick
+```
+
+✅ 正确写法：
+```
+"Cherry-pick 到干净分支，保留意图解决冲突，落不下时说明原因。"
+```
+
+**重点放 gotchas / 负例。**
+
+### Step 3 — 用层次结构
+
+条件性、重型、模板类内容拆到 `scripts/`、`references/`、`assets/`、`config.json`
+
+### Step 4 — 迭代
+
+- 用一个评测集做**小词级调优**
+- 描述里**一字之差就能引发路由级联**
+
+### Step 5 — Ship
+
+---
+
+## 维护：Gotchas 飞轮
+
+Skill 是 **「仅追加为主」** 的：
+
+| 问题 | 对策 |
+|------|------|
+| Agent 错了 | → 加 gotcha |
+| 误加载 | → 收紧描述 + 加负例 |
+| 该加载没加载 | → 加关键词 + 加正例 |
+| system prompt 变了 | → 检查冲突与重复 |
+
+从 80/20 走向 99.9% 的过程，**几乎全靠 gotcha 列表生长**，而不是改描述或加更长的指令。
+
+> 一旦 PR 改描述却没附 evals，"已经走偏了"。
+
+---
+
+## 评测套件分四类
+
+1. **加载评测：** 精度、召回、禁止加载（避免污染邻域）
+2. **渐进加载评测：** Skill 加载后是否正确读取附属文件（如 FORMATTING.md）
+3. **端到端任务评测：** 跑完整 agent loop，用 LLM judge 按 rubric 打分
+4. **跨模型评测：** 在 GPT / Opus / Sonnet 上同时跑（行为差异显著）
+
+---
+
+## 关键 Takeaway
+
+1. **先 evals，后 Skill**；负例与「禁止误载」与正例同等重要
+2. **Description 是最难的一行**，以 `"Load when…"` 起手
+3. **Gotchas 是最高价值内容**，从薄起步、随失败生长
+4. **Action at a distance：** 新增 Skill 会悄无声息地降级现有 Skill —— 这是默认风险，不是边角情况
+5. **写 Skill 的能力本身在复利增长**；任何按日/周/季重复的工作流，都是潜在 Skill

package/docs/research/pmc-gstack-skill-study.md

@@ -0,0 +1,122 @@
+# PMC 与 gstack skill 调查
+
+日期：2026-04-24
+
+## 调查对象
+
+- PMC skill：`/Users/x/.agents/skills/pmc`
+- gstack for Claude：`/Users/x/.claude/skills/gstack`
+- gstack for Codex wrapper：`/Users/x/.codex/skills/gstack`
+
+## PMC 的核心能力
+
+PMC 是状态驱动的 Linear issue 交付编排器。它的价值不是写代码，而是把问题从 triage 推进到 land，并在每个阶段留下可恢复、可审计、可复核的产物。
+
+关键事实：
+
+- 入口文件要求先读 `.omc/pm/<issue>/state.json`，不能凭聊天记忆判断阶段。
+- 阶段路由为 `triage -> plan -> dispatch -> implement -> pr-check -> verify -> qa -> land`。
+- 工作流合同中还有更细的 canonical state machine：
+  `dispatch -> implement -> local-verify -> ac-check -> self-review -> ship -> doc-release -> pr-check -> verify -> qa -> land`。
+- Linear team key 固定为 `GXG`，Linear 是协作前门，不是执行器。
+- 每个阶段都应写入 `.omc/pm/<issue>/...` 下的 JSON/Markdown 产物，并通过 checkpoint 更新状态。
+- 对 bug 工作有 T0/T1/T2 分级；非机械 bug 需要假设、实验和 DEBUG 记录。
+
+PMC 高价值模块：
+
+- `references/phases/`：每个阶段的最小执行指南。
+- `references/workflow-contract.md`：阶段机和阻塞规则。
+- `references/acceptance-contract.md`、`local-verify-contract.md`、`verify-findings-contract.md`、`qa-findings-contract.md`：产物合同。
+- `references/execution-continuity*.md`：上下文丢失后的恢复合同。
+- `scripts/state/checkpoint.py`、`scripts/state/linear_sync.py`：状态推进和 Linear 同步基础。
+- `scripts/render_*_report.py` 与 `write_local_verify.py`：结构化产物到可读报告的桥。
+
+PMC 的限制：
+
+- 强在 issue lifecycle，但不是完整的软件工厂。
+- QA/browser 能力以合同为主，缺少 gstack 那种持久浏览器 runtime。
+- 评审、ship、design/devex、安全、benchmark、canary 等能力需要外部 skill 或人工补齐。
+- 技能发现、上下文恢复、自学习、版本升级、team install、preamble 生成等框架能力相对弱。
+- `/pm land` 按既有结论应只做 gate/handoff，具体 develop merge 交给 merge skill，不应自己定义一套 merge 规范。
+
+## gstack 的核心能力
+
+gstack 是一个把 Claude Code 扩展成“虚拟工程团队”的技能框架。它的能力不只是一组 prompts，而是一套技能分发、持久浏览器、上下文恢复、学习、review/QA/ship 的组合。
+
+关键事实：
+
+- active gstack 安装在 `/Users/x/.claude/skills/gstack`，Codex 侧 `/Users/x/.codex/skills/gstack` 是轻量 wrapper/symlink 面。
+- gstack skill 文档由 `SKILL.md.tmpl` 自动生成，减少命令和文档漂移。
+- 每个 skill 都有 preamble：版本检查、会话计数、配置读取、telemetry 开关、路由提示、context recovery、learning。
+- 浏览器能力采用 long-lived Chromium daemon：CLI 读 `.gstack/browse.json`，通过 localhost HTTP 调 server，server 再通过 CDP 控制 Chromium。
+- 浏览器 server 使用 bearer token、本地绑定、状态文件 0600、cookie 只读复制和 Keychain 授权。
+- 技能覆盖 office-hours、plan、review、investigate、qa、ship、land-and-deploy、canary、benchmark、security、document-release、retro、learn 等完整交付链。
+
+gstack 高价值模块：
+
+- `ARCHITECTURE.md`：browser daemon、ref system、logging、模板生成和测试体系。
+- `docs/skills.md`：技能地图和角色分工。
+- `browse/`：持久浏览器 runtime。
+- `qa/`：Test -> Fix -> Verify loop、health score、截图证据、回归测试生成。
+- `review/`：diff review、specialist dispatch、adversarial review、fix-first。
+- `ship/`：base merge、测试、review、版本/变更日志、PR。
+- `investigate/`：root cause first、3-strike、scope lock、verification report。
+- `bin/gstack-*`：配置、升级、timeline、learning、team init、repo mode 等基础设施。
+
+gstack 的限制：
+
+- 默认面向代码交付和浏览器 QA，不是 Linear-first 的 PM 状态机。
+- 很多流程强绑定 Claude Code 语境，需要抽象成跨宿主协议后才能被 gxpm 复用。
+- `/ship` 是自动化 release flow；gxpm 应保留用户确认和 PMC gate，不应照搬所有自动推送/PR 语义。
+- gstack 强调完整性，但 gxpm 需要区分“可 boil 的 lake”和跨项目、跨团队、跨季度的 ocean。
+
+## gxpm 的替代方向
+
+gxpm 应该采用“重新抽象后的统一产品架构”，而不是“PMC 为骨架，gstack 为肌肉”的组合式 wrapper。
+
+PMC 和 gstack 都应该被拆成 capability source：
+
+- PMC 贡献项目管理状态机、Linear 协作面、artifact gate、checkpoint 和可恢复执行。
+- gstack 贡献技能运行时、浏览器 runtime、QA/review/ship/investigate、context recovery、learn/timeline 和团队化安装。
+- gxpm 负责把这些能力重新定义成统一 state graph、capability runtime、evidence store、policy engine 和 product CLI/skill surface。
+
+吸收 PMC：
+
+- Linear issue 入口与同步。
+- 阶段状态机、checkpoint、artifact-first truth。
+- acceptance/local-verify/verify/qa/land 合同。
+- gate-first 而不是 worker-first 的责任边界。
+
+吸收 gstack：
+
+- skill preamble 框架：版本、配置、会话、路由、上下文恢复。
+- browser daemon 或 browser adapter：为 PMC `qa` phase 提供真实 browser evidence。
+- review/qa/ship 的 report schema 和可验证证据习惯。
+- learn/timeline/context-save/context-restore 的持久上下文机制。
+- template-generated skill docs，避免手写命令漂移。
+- specialist map：review、security、design、devex、benchmark、canary 等作为可选能力包。
+
+避免：
+
+- 不把 gxpm 写成 PMC/gstack 的兼容壳。
+- 不保留 `.omc` 与 `.gstack` 两套长期真值。
+- 不把 gstack 整树 vendoring 进 gxpm。
+- 不把 PMC phase guide 简单改写成另一个手册。
+- 不让 Linear 执行代码或替代本地状态。
+- 不在 V0 同时实现所有 runtime、browser、review、ship、deploy 能力。
+
+## 建议的 V0 定义
+
+V0 只做四件事：
+
+1. 定义 gxpm 原生 state graph、artifact store、evidence store。
+2. 定义 capability runtime：issue、planning、execution、review、browser、release、memory、skill。
+3. 建立 PMC/gstack replacement map，明确每项旧能力迁移到哪个 gxpm 模块。
+4. 写出 gxpm skill 入口，让代理能先读 state，再按最小引用面加载对应 gxpm capability guide。
+
+V0 成功信号：
+
+- 一个代理能在不加载 PMC/gstack 的情况下，从 gxpm issue/state 进入正确阶段。
+- 每个阶段都知道调用哪个 gxpm capability、写哪些产物、什么时候停止。
+- browser QA 能力被定义为 adapter/gate，而不是散落在 prompt 里的“去测一下”。
+- Linear 同步失败时可以安全降级，本地状态仍然完整。

package/docs/research/spec-kit-study.md

@@ -0,0 +1,224 @@
+# Spec Kit 深度架构研究报告
+
+> 研究日期：2026-05-05
+> 来源：GitHub 官方开源项目 `spec-kit`（本地路径 `/Users/x/Desktop/Project/github/spec-kit`）
+> 研究目的：从技术架构师视角分析 Spec-Driven Development 工具链的架构约束，为 gxpm 引入规格驱动开发能力提供决策依据
+
+---
+
+## 一、项目定位
+
+**Spec Kit** 是 GitHub 官方开源的 **Spec-Driven Development (SDD)** 工具包与 CLI。其核心主张是将软件规格说明（Specification）提升为**可执行的主要产物**，而非代码的附属文档。
+
+产品形态：
+- `specify` CLI（Python，Typer 框架）
+- 模板系统（Markdown/TOML/YAML 命令模板）
+- 工作流引擎（YAML 驱动，10 种步骤类型）
+- 扩展/预设双系统（第三方能力接入与行为定制）
+- 30+ AI 编码助手集成（Claude Code、Codex、Kimi、Cursor 等）
+
+---
+
+## 二、架构概览
+
+### 2.1 目录结构
+
+```
+spec-kit/
+├── src/specify_cli/           # CLI 核心源码（~14.8k 行 Python）
+│   ├── __init__.py            # 主 CLI 入口（5,869 行，含所有子命令）
+│   ├── agents.py              # CommandRegistrar：命令注册与多代理格式渲染
+│   ├── extensions.py          # ExtensionManager：扩展生命周期管理
+│   ├── presets.py             # PresetManager：预设生命周期与模板解析
+│   ├── integrations/          # AI 助手集成抽象层（30+ 个）
+│   │   ├── base.py            # IntegrationBase 及四大子类抽象
+│   │   └── <agent>/           # 每助手一个子包（claude/、gemini/、kimi/ 等）
+│   └── workflows/             # 工作流引擎
+│       ├── engine.py          # WorkflowDefinition、WorkflowEngine、RunState
+│       ├── expressions.py     # Jinja2-like 表达式求值
+│       └── steps/             # 10 种内置步骤（command/shell/prompt/gate/if/…）
+├── templates/                 # 核心页面模板与命令模板
+├── scripts/                   # Bash/PowerShell 辅助脚本
+├── extensions/                # 扩展系统文档与内置 git 扩展
+├── presets/                   # 预设系统文档与内置预设
+├── tests/                     # ~25.7k 行测试代码（61 个文件）
+└── docs/                      # DocFx 文档站点
+```
+
+### 2.2 技术栈
+
+| 层级 | 技术 |
+|------|------|
+| 语言 | Python 3.11+ |
+| CLI | Typer（Click） |
+| 构建 | Hatchling |
+| TUI | Rich |
+| 配置 | PyYAML、json5 |
+| 版本兼容 | `packaging.SpecifierSet` |
+| 路径规则 | `pathspec`（.gitignore 语义） |
+| 测试 | pytest + pytest-cov |
+| Lint | ruff |
+| CI/CD | GitHub Actions |
+
+---
+
+## 三、核心抽象与概念模型
+
+### 3.1 四层可扩展性栈（优先级从高到低）
+
+| 层级 | 路径 | 作用 |
+|------|------|------|
+| 1. Project-Local Overrides | `.specify/templates/overrides/` | 一次性本地调整 |
+| 2. Presets | `.specify/presets/<id>/` | 可共享、可堆叠的模板/命令/脚本覆盖 |
+| 3. Extensions | `.specify/extensions/<id>/` | 新增能力与外部工具集成 |
+| 4. Core | `.specify/templates/` | 内置默认模板 |
+
+**关键设计**：Templates 在**运行时**解析（走优先级栈），而 Extension/Preset 的 commands 在**安装时**写入代理目录。
+
+### 3.2 集成抽象（Integration Registry）
+
+所有 AI 助手通过 `IntegrationBase` 注册到全局 `INTEGRATION_REGISTRY`：
+
+- `IntegrationBase` — 抽象基类，定义 `key`、`config`、`setup()`、`teardown()`
+- `MarkdownIntegration` — `.md` 命令格式，覆盖 ~20 个代理
+- `TomlIntegration` — `.toml` 格式，用于 Gemini、Tabnine
+- `YamlIntegration` — YAML recipe，用于 Goose
+- `SkillsIntegration` — `SKILL.md` 目录布局，用于 Codex、Kimi 等
+
+**设计约束**：CLI 型集成（`requires_cli: True`）的 `key` 必须与实际可执行文件名匹配，以便 `shutil.which(key)` 检测。
+
+### 3.3 工作流引擎
+
+状态机驱动的执行引擎：
+
+```
+CREATED → RUNNING → [COMPLETED | PAUSED | FAILED | ABORTED]
+            ↑___________|
+```
+
+- `WorkflowDefinition`：从 YAML 解析（id/name/version/inputs/steps）
+- `WorkflowEngine`：加载 → 校验 → 执行 → 持久化 → 恢复
+- `RunState`：每步后保存到 `.specify/workflows/runs/{run_id}/state.json`
+- `StepContext`：传递 inputs、steps 结果、item、fan_in 等上下文
+
+10 种内置步骤：command、shell、prompt、gate、if_then、switch、while_loop、do_while、fan_out、fan_in。
+
+### 3.4 扩展与预设生命周期
+
+| 组件 | 核心类 | 注册表 |
+|------|--------|--------|
+| 扩展 | `ExtensionManager`、`ExtensionManifest` | `.specify/extensions/.registry` |
+| 预设 | `PresetManager`、`PresetManifest` | `.specify/presets/.registry` |
+
+两者均支持：
+- 目录系统（`catalog.json` + `catalog.community.json`）
+- ZIP 下载安装、版本兼容性检查（PEP 440）
+- 命令注册到代理目录、卸载时清理
+- 技能模式（`--ai-skills`）下生成 `SKILL.md`
+
+---
+
+## 四、架构约束（显式与隐式）
+
+### 4.1 显式约束
+
+| 约束 | 来源 | 说明 |
+|------|------|------|
+| Python >= 3.11 | `pyproject.toml` | 现代语法依赖 |
+| 模板运行时解析栈 | `presets/ARCHITECTURE.md` | Override > Preset > Extension > Core，不可绕过 |
+| 命令命名空间 | `extensions.py` | 扩展命令必须遵循 `speckit.{ext-id}.{cmd}`，不可 shadow core |
+| 语义版本 | Manifest | PEP 440，`SpecifierSet` 校验 |
+| 预设组合策略 | `presets.py` | 仅 replace/prepend/append/wrap 四种；script 仅 replace/wrap |
+| 工作流 schema_version | `engine.py` | 仅支持 `1.0` |
+| 步骤 ID 唯一性 | `engine.py` | 不允许 `:` 字符（保留给引擎嵌套 ID） |
+| Agent CLI Key 匹配 | `AGENTS.md` | `requires_cli=True` 时 `key` 必须等于可执行文件名 |
+| 上下文文件标记 | `base.py` | `<!-- SPECKIT START -->` / `<!-- SPECKIT END -->` 管理注入段 |
+| 路径逃逸防护 | `agents.py`、`extensions.py` | 所有写入通过 `_ensure_inside()` 校验 |
+
+### 4.2 隐式约束
+
+| 约束 | 推断依据 | 架构影响 |
+|------|---------|---------|
+| **单例注册表模式** | `INTEGRATION_REGISTRY`、`STEP_REGISTRY` 为全局字典 | 不支持动态卸载；扩展新步骤需修改源码并重启 |
+| **同步 I/O 为主** | `subprocess.run`、文件读写均为同步阻塞 | 工作流 fan-out 实际顺序执行；无法利用异步并发 |
+| **无数据库/无服务器** | 所有状态以 JSON/YAML 文件落盘 | 适合本地 CLI，无法天然支持多机协作或服务化 |
+| **Template-First 设计** | 核心逻辑依赖 Markdown 模板占位符替换 | 复杂条件逻辑难以在模板中表达，必须下沉到 Python/shell |
+| **单项目隔离** | 所有产物落在 `.specify/` 目录下 | 不支持跨项目复用配置（除非通过 `~/.specify/`） |
+| **代理目录耦合** | 安装时直接写入 `.claude/commands/` 等 | 代理升级或目录结构变更会导致不兼容 |
+| **无网络服务治理** | 扩展下载直接拉取 GitHub raw/ZIP | 无镜像、无缓存失效策略、无重试机制 |
+| **强一致性文件状态假设** | 注册表、manifest、模板文件必须同时一致 | 手动修改 `.specify/` 易导致状态不一致 |
+
+### 4.3 宪法级约束（SDD 方法论）
+
+`spec-driven.md` 中阐述的 **Nine Articles of Development**：
+
+1. **Library-First**：每个特性必须先以独立库形式存在
+2. **CLI Interface Mandate**：所有库必须暴露 CLI（stdin/stdout，支持 JSON）
+3. **Test-First Imperative**：严格 TDD，红-绿-重构
+4. **Composition over Inheritance**：优先组合
+5. **Explicit over Implicit**：显式优于隐式
+6. **Fail Fast, Fail Loud**：快速失败、大声失败
+7. **Simplicity Gate**：最多 3 个项目/模块
+8. **Anti-Abstraction**：直接使用框架特性，禁止过度包装
+9. **Integration-First Testing**：优先使用真实环境而非 mock
+
+这些约束通过模板中的 Phase -1 Gates 强制执行，是 Spec Kit 生成代码的元级约束。
+
+---
+
+## 五、模块耦合分析
+
+### 5.1 高耦合点
+
+1. **`presets.py` ↔ `extensions.py`**：预设命令注册时需检查扩展是否已安装；预设卸载后需调和技能目录。
+2. **`agents.py` ↔ `integrations/base.py`**：`CommandRegistrar` 的 `AGENT_CONFIGS` 在运行时从 `INTEGRATION_REGISTRY` 派生，存在循环导入风险（通过懒加载和 `try/except ImportError` 处理）。
+3. **`__init__.py` ↔ 所有子模块`**：主 CLI 文件导入并委托给各子模块，形成事实上的 Facade，但单文件膨胀至近 6,000 行。
+
+### 5.2 低耦合点
+
+- `workflows/` 子系统几乎独立于扩展/预设系统
+- `integrations/` 子包之间完全独立（每代理一个文件，通常 <30 行）
+
+---
+
+## 六、限制与风险
+
+### 6.1 显式文档化的限制
+
+1. **Resume 粒度限制**：嵌套步骤（`if`/`switch`/`while` 内）暂停后，resume 会重新运行父控制流步骤及其嵌套体。精确 resume（嵌套步骤路径栈）是计划中的增强。
+2. **Requirements 未强制**：`engine.py` 中声明但未在运行时强制。
+3. **Windows Bash 测试跳过**：`test.yml` 中注明，无 MSYS2/MINGW 时 bash 测试自动跳过。
+
+### 6.2 代码推断的限制
+
+1. **单体 CLI 文件膨胀**：`__init__.py` 近 6,000 行，未按子命令拆分。
+2. **同步架构天花板**：所有 I/O 同步，fan-out 无真正并行。
+3. **模板表达能力受限**：复杂逻辑无法在 Markdown 模板中表达。
+4. **多代理维护负担**：30+ 集成子包大部分为 10-30 行重复声明，代理格式变更需逐一手动更新。
+5. **扩展生态信任模型**：社区扩展采用策展而非代码审计模型，官方声明不审查扩展代码本身。
+6. **无内置迁移/升级工具**：`specify upgrade` 依赖 git 拉取，对非 git 或已重度定制项目的升级策略不明确。
+
+---
+
+## 七、对 gxpm 的映射参考
+
+| Spec Kit 能力 | gxpm 映射参考 | 借鉴优先级 |
+|--------------|--------------|-----------|
+| **SDD 宪法（Nine Articles）** | `docs/governance/development-contract.md` 可引入规格驱动开发章节 | 高 |
+| **四层可扩展性栈** | gxpm 的 `skills/` + `templates/` + `.gxpm/local/` 可对标为 Override/Preset/Extension/Core | 高 |
+| **工作流引擎** | gxpm 当前 phase gate（triage→plan→dispatch→…→land）可升级为 YAML 可声明的状态机 | 中 |
+| **Integration Registry** | `hosts/claude.ts`、`hosts/codex.ts` 可升级为统一的宿主适配注册表 | 高 |
+| **模板运行时解析** | skill 的 `*.tmpl` 生成机制可借鉴优先级栈覆盖逻辑 | 中 |
+| **扩展/预设目录系统** | gxpm 的 capability runtime 可引入社区扩展目录与版本兼容检查 | 低 |
+| **SKILL.md 生成模式** | 已有 `bun run gen:skill-docs`，可引入 `--ai-skills` 多宿主批量生成 | 中 |
+| **工作流 Resume 机制** | gxpm 的 checkpoint/execution continuity 可借鉴状态持久化与恢复模型 | 中 |
+
+---
+
+## 八、关键结论
+
+1. **Spec Kit 的核心价值不是代码，是方法论**：SDD 宪法和四层可扩展性栈是最大资产，工作流引擎和模板系统是实现载体。
+2. **同步+文件系统状态机是天花板也是护城河**：适合本地 CLI 场景，但服务化/协作化需要重构核心引擎。
+3. **30+ 宿主集成的维护模式不可复制**：gxpm 应采用"协议抽象+代码生成"而非"手写 30 个适配文件"。
+4. **扩展/预设双系统提供了清晰的定制边界**：Override > Preset > Extension > Core 的优先级栈可直接借鉴到 gxpm 的 skill/template 系统。
+5. **工作流引擎的 resume 和 gate 步骤与 gxpm 的 phase gate 天然互补**：可将 gxpm 的 phase 推进逻辑从硬编码 TypeScript 升级为声明式 YAML 工作流。