@shirayner/ace 0.1.0-snapshot.1

package/templates/skills/skill-optimize/references/quality-checklist.md

@@ -0,0 +1,170 @@
+# 质量检查清单与精简方法论
+
+> 本文件提供详细的诊断检查清单、transcript 分析指南和精简方法论。
+> 做深度优化时阅读。
+
+---
+
+## 目录
+
+1. [完整诊断检查清单](#完整诊断检查清单)
+2. [Transcript 分析指南](#transcript-分析指南)
+3. [精简方法论](#精简方法论)
+4. [Description 优化指南](#description-优化指南)
+5. [优化过程反模式](#优化过程反模式)
+
+---
+
+## 完整诊断检查清单
+
+### 触发层检查
+
+| 检查项 | 通过标准 | 未通过的处理 |
+|--------|---------|-------------|
+| 职责一句话 | 能用"动词+名词"概括 | 回到单一职责原则 |
+| 正面触发覆盖 | 列出 ≥5 种用户会说的触发短语 | 补充触发场景 |
+| 负面排除明确 | 列出与相邻 skill 的边界 | 添加 DO NOT trigger 条件 |
+| 非显式触发 | 覆盖用户不直接提及 skill 名但需要它的场景 | 补充隐式触发用例 |
+| 长度适中 | Description 在 50-150 词之间 | 精简或扩展 |
+
+### 认知层检查
+
+| 检查项 | 通过标准 | 未通过的处理 |
+|--------|---------|-------------|
+| 使命声明 | 前 2 行说明目的和理念 | 添加使命声明 |
+| 总行数 | ≤500 行 | 移内容到 references/ |
+| 原则/流程比 | 原则在前，流程在后 | 重新排序 |
+| ALWAYS/NEVER 数量 | 每个都附有原因 | 替换为推理解释 |
+| 验证点 | 至少有 1 个显式验证步骤 | 添加验证环节 |
+| references 指引 | 明确说明何时阅读哪个文件 | 添加指引语句 |
+| 复杂度路径 | 支持不同复杂度的输入 | 添加分流逻辑 |
+| 反模式 | 列出常见错误及修复方向 | 补充反模式表 |
+
+### 资源层检查
+
+| 检查项 | 通过标准 | 未通过的处理 |
+|--------|---------|-------------|
+| 独立可用 | 每个文件单独加载仍有价值 | 重组为自包含单元 |
+| 大文件有目录 | >300 行的文件有目录 | 添加目录 |
+| 无孤立文件 | 每个文件都从 SKILL.md 引用 | 删除或添加引用 |
+| 内容分层正确 | 核心知识在认知层，细节在资源层 | 上移或下移内容 |
+
+---
+
+## Transcript 分析指南
+
+阅读执行 transcript 是最被忽视但最有价值的优化实践。
+
+### 观察什么
+
+**Token 浪费**：
+- AI 是否在不需要的步骤上花费大量 token？
+- 是否有长时间的"思考"或"犹豫"，显示指令不清晰？
+- 是否加载了不需要的 reference 文件？
+
+**推理偏差**：
+- AI 是否正确理解了指令意图？
+- 如果理解有偏差，是表达问题还是 AI 能力问题？
+- AI 的决策路径是否合理？
+
+**重复模式**：
+- 多个测试用例是否独立写了相似的辅助脚本？→ 考虑捆绑到 scripts/
+- 多个测试用例是否在同一个地方犯了同样的错？→ 在那个判断节点增加指引
+
+**时间分布**：
+- 哪个阶段消耗最多时间？
+- 是否有阶段可以简化或跳过？
+
+### 分析模板
+
+对每个测试用例的 transcript：
+
+```
+1. 总 token 消耗：___
+2. 关键偏差点：___（在哪里偏离了预期？）
+3. 浪费最大的段落：___（什么指令导致了无用功？）
+4. 重复工作：___（与其他测试用例有什么重复？）
+5. 优化建议：___
+```
+
+---
+
+## 精简方法论
+
+精简不是"删减"，而是"提纯"。
+
+### 三步法
+
+**第一步：删除不改变行为的语句**
+
+逐句审查。删掉一句话后，skill 的行为会改变吗？如果不会，它是噪声。
+
+常见可删除内容：
+- "请注意以下几点……"（直接列出即可）
+- "这一点非常重要，因为……"（如果真的重要，结构位置应体现重要性）
+- "你需要确保……"（祈使语气直接说"确保……"）
+- 对 AI 已知概念的解释（如"API 是一种接口"）
+
+**第二步：合并重复表达**
+
+同一个意思出现多次时，保留表达最清晰的那次。检查方法：搜索关键词，看是否在多处重复了相同约束。
+
+**第三步：上移抽象层级**
+
+把具体的"做什么"替换为抽象的"判断什么"。
+
+| 变换前（具体） | 变换后（抽象） |
+|---------------|---------------|
+| "用 try-catch 包裹所有 API 调用" | "在系统边界（外部 API、用户输入）做错误处理，内部代码信任框架保证" |
+| "函数名用 camelCase" | "命名遵循项目现有约定，保持一致性" |
+| "每个文件不超过 200 行" | "文件长度应反映单一职责——如果需要滚动很远才能理解全貌，考虑拆分" |
+
+### 过度精简的危险信号
+
+- AI 开始在关键节点犯错（信息不足）
+- AI 的输出质量明显下降（关键约束被删除了）
+- AI 不再触发该 skill（description 太简短）
+
+遇到这些信号时，回退上一步精简，找到平衡点。
+
+---
+
+## Description 优化指南
+
+### 黄金结构
+
+```
+[做什么] + [何时触发——列举场景和措辞] + [何时不触发] + [与相邻 skill 的边界]
+```
+
+### 提升召回率（减少 Undertrigger）
+
+- 列举多种触发场景和用户措辞（包括口语化、缩写、中英文混用）
+- 包含用户不直接提及 skill 名但需要此 skill 的场景
+- 使用"推进式"描述——主动声明适用场景
+- 覆盖非典型用例
+
+### 提升精确率（减少 Overtrigger）
+
+- 添加 DO NOT trigger 条件
+- 明确排除与相邻 skill 的职责边界
+- 避免过于宽泛的描述词（如"任何与代码相关的"）
+
+### 关于触发机制的理解
+
+Skill 出现在 Claude 的 `available_skills` 列表中，Claude 基于 description 做语义匹配决定是否调用。关键点：Claude 只在认为 skill 能提供超出自身能力的价值时才触发——简单的一步操作（如"读取这个文件"）即使 description 匹配也可能不触发。
+
+因此测试查询应足够复杂，让 Claude 有理由调用 skill。
+
+---
+
+## 优化过程反模式
+
+| 反模式 | 症状 | 解决方向 |
+|--------|------|----------|
+| 批量修改 | 一次改多处，无法定位哪个改动起效 | 每次只改一处，改完验证 |
+| 只看结果不看过程 | 只评价最终输出，忽略 transcript 中的浪费 | 阅读完整的执行过程记录 |
+| 完美主义 | 无限迭代不交付，追求 100% | 定义完成标准，满意即止 |
+| 经验丢失 | 每次优化从零开始，不记录发现 | 维护优化日志 |
+| 数据缺失 | 凭感觉判断优劣，没有对比数据 | 用 skill-creator 的 eval 基础设施量化 |
+| 过早优化 | skill 还没基本功能就开始精简 | 先让 skill 工作，再优化 |

package/templates/skills/skill-optimize/references/theory-foundations.md

@@ -0,0 +1,201 @@
+# 理论基础：七条原则的深层根基
+
+> 本文件提供每条优化原则背后的理论依据。在需要理解"为什么这条原则有效"时阅读。
+> 日常优化参考 SKILL.md 中的精炼版即可。
+
+---
+
+## 目录
+
+1. [Skill 的本质](#skill-的本质)
+2. [原则一：传意不传形 — 理论基础](#原则一传意不传形)
+3. [原则二：渐进披露 — 理论基础](#原则二渐进披露)
+4. [原则三：信噪比优化 — 理论基础](#原则三信噪比优化)
+5. [原则四：单一职责 — 理论基础](#原则四单一职责)
+6. [原则五：闭环验证 — 理论基础](#原则五闭环验证)
+7. [原则六：复杂度适配 — 理论基础](#原则六复杂度适配)
+8. [原则七：抗过拟合 — 理论基础](#原则七抗过拟合)
+9. [理论来源索引](#理论来源索引)
+
+---
+
+## Skill 的本质
+
+剥离所有技术细节后，Skill 的本质是：
+
+> **一个将人类领域知识编码为 AI 可执行的认知协议的接口。**
+
+- **人类领域知识**：承载的是专家的思维方式和判断标准，不是操作步骤
+- **编码**：将波兰尼所说的"默会知识"外显化为可传递的形式
+- **AI 可执行**：不是给人看的文档，而是给 AI 理解和执行的认知框架
+- **认知协议**：不是命令序列（"先做A再做B"），而是思维协议（"在此情境下如此判断"）
+
+### Skill 的成熟度光谱
+
+```
+Level 0: 操作手册 — "先做A，再做B，如果C则做D"
+Level 1: 决策树   — "在X情况下选择Y，因为Z"
+Level 2: 原则框架 — "遵循这些原则，在具体情境中自主判断"
+Level 3: 认知协议 — "像这个领域的专家一样思考"
+```
+
+Level 0-1 易过时（步骤和条件会变），Level 2-3 持久（原则和思维方式很少过时）。优化方向是让核心部分向 Level 2-3 演进。
+
+---
+
+## 原则一：传意不传形
+
+### 理论根基
+
+**Constitutional AI（Anthropic）**：让 AI 内化原则而非记忆规则。内化原则的 AI 能在新情境中自主做出符合设计意图的判断。
+
+**维特根斯坦的语言游戏**：词语的意义不在于定义，而在于使用。过度具体的规则在新语境中失效，而抽象原则可以被重新诠释以适应新情境。
+
+**波兰尼的默会知识**："我们知道的比能说出来的多。"最高效的知识传递不是列规则，而是展示专家面对歧义时的判断过程。
+
+### 为什么 ALWAYS/NEVER 是黄旗
+
+硬性规则传递的是*形式*（在所有情况下做X），而非*意图*（因为Y原因，在Z情境下做X是好的）。Claude 具备 Theory of Mind，给出原因后它能自主判断边界情况。硬性规则反而剥夺了这种判断能力。
+
+当然，某些约束确实需要硬性规则（如安全性、合规性）。此时附上原因说明，让 AI 理解为什么这是不可协商的。
+
+---
+
+## 原则二：渐进披露
+
+### 理论根基
+
+**认知负荷理论（Sweller）**：工作记忆有限。认知负荷分三类：
+- 内在负荷：材料本身的复杂度
+- 外在负荷：呈现方式造成的无谓消耗
+- 关联负荷：构建知识图式的有益努力
+
+目标：最小化外在负荷，最大化关联负荷。
+
+**分块理论（Miller）**：短期记忆处理约 7±2 个信息块。通过层级结构（原则 → 标准 → 检查项）实现信息的递进分块。
+
+**脚手架理论（Vygotsky）**：学习发生在"最近发展区"。Skill 应设计渐进式支持结构——核心指令是永久脚手架，references/ 是按需脚手架。
+
+### 上下文窗口是稀缺资源
+
+所有 skill 的 description 共享上下文预算。始终在上下文中的触发层必须极度精简（~100 词/skill）。认知层在触发后加载，应控制在 500 行以内。资源层按需加载，无大小限制。
+
+---
+
+## 原则三：信噪比优化
+
+### 理论根基
+
+**Shannon 信息论**：Prompt 是信道，用户意图是信号，歧义和冗余是噪声。指令设计的本质是信噪比优化。
+
+**奥卡姆剃刀**：如无必要，勿增实体。每条指令需要证明自己存在的必要性。
+
+### 信号密度的量化思考
+
+- 关键行为约束用结构化格式（表格、列表）——高信号密度
+- 背景信息极简表达——必要但不喧宾夺主
+- 5 条精确的规则胜过 20 条模糊的规则
+- 指令长度应与任务复杂度匹配——不是越短越好，也不是越详尽越好
+
+### 冗余的悖论
+
+适度冗余保护核心信息——关键原则在不同位置重复强调是信号。过度冗余降低 SNR——同一信息无新上下文的重复是噪声。区分标准：这次重复是否增加了新的上下文或视角？
+
+---
+
+## 原则四：单一职责
+
+### 理论根基
+
+**SOLID-SRP（Robert C. Martin）**：一个模块只应因为一个理由而改变。
+
+**Unix 哲学**：做一件事并做好。通过组合实现复杂能力。
+
+**OpenAI Agent 最佳实践**：渐进复杂度——从简单开始，只在需要时增加复杂度。
+
+### 触发的经济学
+
+模糊职责的 Skill 在触发匹配时产生歧义——AI 不确定何时该用。这导致两种失败：
+1. Undertrigger：该用时没用（召回率低）
+2. Overtrigger：不该用时用了（精确率低）
+
+清晰的单一职责让 description 可以精确描述"做什么"和"何时用"，从而提升触发准确率。
+
+---
+
+## 原则五：闭环验证
+
+### 理论根基
+
+**控制论（Wiener）**：闭环控制是可靠系统的必要条件。反馈的延迟和质量决定系统稳定性。
+
+**波利亚的问题解决四步法**："回顾"阶段是理解和泛化的关键。
+
+**Reflexion 架构**：通过自我反思从失败中学习。
+
+### 开环的指数风险
+
+开环控制（给指令后不检查结果）在复杂任务中的失败率随步骤数指数增长。假设每步成功率 90%，10 步后整体成功率仅 35%。验证点的作用是在失败扩散前截断错误链。
+
+---
+
+## 原则六：复杂度适配
+
+### 理论根基
+
+**双过程理论（Kahneman）**：思维分为 System 1（快速直觉）和 System 2（慢速分析）。常规任务应可由"快思考"处理，只在需要深度推理时才激活"慢思考"。这就是复杂度分流的认知科学基础。
+
+**有限理性（Simon）**：不追求"最优流程"的幻觉，而提供"足够好"的决策框架。何时停止优化本身就是一个需要设计的判断准则。
+
+**必要多样性定律（Ashby）**：控制系统的复杂度必须至少与被控系统相当。简单指令无法可靠控制复杂任务——但过度复杂的指令在简单任务上是浪费。
+
+---
+
+## 原则七：抗过拟合
+
+### 理论根基
+
+**ML 泛化理论**：训练集上表现完美但测试集上失败 = 过拟合。Skill 的"训练集"是测试用例，"测试集"是真实用户输入。为特定测试用例量身定做的修改是过拟合。
+
+**锚定效应（Kahneman）**：示例具有极强的锚定力量——它们会成为输出的隐性模板。坏的示例比没有示例更危险，因为它会锚定所有后续输出。
+
+**Anthropic 的 "Generalize from Feedback"**：从反馈中提炼通用原则，而非为特定失败打补丁。
+
+### 健康的示例设计
+
+- 3-5 个多样化示例，覆盖不同场景
+- 展示推理过程，而非仅展示最终结果
+- 示例之间应有足够差异性，避免锚定到单一模式
+- 定期用新的、未见过的输入测试 skill
+
+---
+
+## 理论来源索引
+
+### 认知科学
+- John Sweller — 认知负荷理论
+- George Miller — 分块理论（7±2 法则）
+- Lev Vygotsky — 最近发展区与脚手架理论
+
+### 心理学
+- Daniel Kahneman — 双过程理论、锚定效应
+- Herbert Simon — 有限理性与满意解
+
+### 哲学
+- Ludwig Wittgenstein — 语言游戏
+- Michael Polanyi — 默会知识
+- William of Ockham — 奥卡姆剃刀
+
+### 信息论与控制论
+- Claude Shannon — 信息熵、信噪比
+- Norbert Wiener — 反馈循环与闭环控制
+- W. Ross Ashby — 必要多样性定律
+
+### 软件工程
+- Robert C. Martin — SOLID 原则
+- Unix 哲学 — 做一件事并做好
+
+### AI Agent 设计
+- Anthropic — Building Effective Agents、Constitutional AI
+- OpenAI — A Practical Guide to Building Agents
+- 学术界 — ReAct、Plan-and-Execute、Reflexion 架构