sakitA/spec-kit-optimize

# Spec-Kit Optimize 扩展 审计并优化 AI 治理文档的上下文效率。专为长期 AI 驱动的开发设计，适用于治理规则有机增长并累积 token 负债的场景。 ## 本扩展存在的原因 在 AI 驱动的开发中，constitution 会被加载到每个 AI 会话的上下文窗口中。随着时间的推移： - **Token 膨胀**：规则、示例和版本历史不断积累——每次调用都会消耗 token - **规则衰退**：针对特定事件的规则永久存在，因为 AI 缺乏制度记忆 - **不确定性治理**：模棱两可的规则导致不同的 AI 会话表现不同 - **治理回声**：同一规则在多个文件中重复声明，浪费 token 并可能导致矛盾 - **缺乏学习闭环**：AI 会话重复犯同样的错误，却没有机制来捕获经验教训 此扩展提供了检测和修复这些问题的工具。 ## 安装 ``` # 从 spec-kit 目录（发布时） specify extension add optimize # 从直接 URL specify extension add optimize --from https://github.com/sakitA/spec-kit-optimize/archive/refs/tags/v1.0.0.zip # 用于本地开发 specify extension add --dev /path/to/spec-kit-optimize ``` ## 命令 ### `/speckit.optimize.run` — Constitution 审计 分析与 AI 驱动开发密切相关的 6 大类 constitution 指标： 1. **Token 预算分析** — 衡量各部分的 token 成本和治理密度 2. **规则健康度分析** — 检测过时、针对特定事件、已废弃和已毕业的规则 3. **AI 可解释性分析** — 发现歧义、矛盾和无法执行的规则 4. **语义压缩** — 识别可折叠的规则簇、冗余示例以及内联到引用的转换机会 5. **Constitution 一致性** — 评估原则平衡、规则分散度、交叉引用、CLAUDE.md 偏移 6. **治理回声检测** — 查找跨文件重复和总治理 token 预算 ``` # 完整审计 /speckit.optimize.run # 单一类别 /speckit.optimize.run --category token_budget # 仅报告（无 apply 步骤） /speckit.optimize.run --report-only ``` ### `/speckit.optimize.tokens` — Token 使用追踪器 衡量所有治理文件和扩展命令的 token 占用情况。追踪随时间变化的趋势。 ``` # 完整 token 报告 /speckit.optimize.tokens # 与先前报告对比 /speckit.optimize.tokens --diff # 仅 extensions（跳过治理文件） /speckit.optimize.tokens --extensions-only ``` ### `/speckit.optimize.check` — Constitution 违规检查 按需合规审计：根据 constitution 中的每条原则检查当前功能的 spec、plan、tasks 以及可选的实现代码。捕获在内置 `/speckit.plan` 和 `/speckit.analyze` 关卡之间通过手动编辑引入的违规。 ``` # 根据 constitution 检查 active feature /speckit.optimize.check # 检查特定 feature /speckit.optimize.check --feature user-authentication # 同时扫描 implementation 源文件 /speckit.optimize.check --include-code # 仅显示 critical violations /speckit.optimize.check --severity CRITICAL ``` | 参数 | 描述 | 默认值 | |----------|-------------|---------| | `--feature ` | 指定特定功能而非自动检测 | 当前功能 | | `--include-code` | 同时扫描 tasks 中引用的实现源文件 | 禁用 | | `--severity ` | 筛选 CRITICAL、HIGH 或 ALL | ALL | **工作原理：** 1. 使用 RFC 2119 关键字（MUST、SHOULD 等）将 constitution 解析为单独的原则 2. 加载功能的 spec.md、plan.md 和 tasks.md 3. 评估每条原则是否存在矛盾、遗漏、结构性违规和语义偏移 4. 报告违规情况及其严重程度（MUST 为 CRITICAL，SHOULD 为 HIGH，模棱两可为 MEDIUM） 5. 为每项发现提供证据和位置 **钩子：** `/speckit.implement` 完成后，系统会提示您自动运行此检查。这能在最早的有利时机捕获违规——即代码编写完成但尚未提交之前。 ### `/speckit.optimize.learn` — 会话学习 会话结束分析：检测 AI 错误模式、重复修正和治理缺口。建议添加 constitution 规则或 memory 条目以防止复发。 ``` # 完整 session 分析 /speckit.optimize.learn # 仅规则（无 memory 建议） /speckit.optimize.learn --rules-only # 从特定 commit 分析 /speckit.optimize.learn --since abc1234 ``` ## 设计理念 **默认仅建议。** 每个命令首先生成报告。在用户明确批准之前不会修改任何内容。流程始终为：分析 → 报告 → 提议 → 用户同意 → 应用。 **Spec-kit 标准路径。** 该扩展适用于任何 spec-kit 项目。它使用 `.specify/memory/constitution.md` 作为主 constitution 路径，并遵循重定向以适应项目特定的布局。它从不对特定项目的路径进行硬编码。 **语义保留。** 优化去除的是表达上的冗余，而非意图。每一条治理规则都能在压缩后保留——改变的只是其 token 成本。 ## 配置 将 `config-template.yml` 复制到扩展目录下的 `optimize-config.yml`： ``` cp .specify/extensions/optimize/config-template.yml \ .specify/extensions/optimize/optimize-config.yml ``` 关键设置： - `check.include_code_by_default` — 无需 `--include-code` 标志即可扫描实现文件 - `check.min_severity` — 报告的最低严重级别（CRITICAL、HIGH、MEDIUM 或 ALL） - `categories.*` — 开关单个分析类别 - `thresholds.max_constitution_tokens` — 标记超过此 token 估值的 constitution - `thresholds.governance_budget_percent` — 治理开销占上下文窗口的最大百分比 - `target_context_window` — 用于预算计算的上下文窗口大小（默认：200K） - `learn.min_corrections_to_flag` — 标记模式前所需的最小重复修正次数 ## 集成 - **`/speckit.constitution`** — 编写工具。Optimize 将其移交以应用批准的更改并进行适当的版本升级。 - **`/speckit.analyze`** — 一致性检查器。在优化后运行以验证跨工件的一致性。 - **`/speckit.optimize.check`** → **`/speckit.optimize.run`** — 如果发现违规，运行完整审计以优化 constitution。 - **`/speckit.optimize.tokens`** → **`/speckit.optimize.run`** — 如果 token 追踪器显示治理开销过高，运行完整审计。 - **`/speckit.optimize.learn`** → **`/speckit.constitution`** — 来自会话学习的批准规则通过 constitution 技能应用。 ## 报告 报告保存至 `.specify/optimize/`（需用户同意）： - `token-report.md` — 最新 token 使用快照（支持历史趋势） - `learning-report-.md` — 单次会话学习分析 ## 需求 - Spec-Kit >= 0.1.0 - 现有的已填充 constitution（非原始模板） - Git 仓库（用于 learn 命令的会话分析） ## 许可证 MIT

标签：AI开发工具, AI治理, GPT工程, LLM上下文管理, RESTful API, Spec-Kit扩展, Token预算, 上下文窗口, 代码宪法, 去重, 可解释性, 技术债, 提示词优化, 治理文档, 网络安全研究, 自动化治理, 规则健康度, 规则审计, 语义压缩, 语义网, 防御加固