From 3c05d54303695961daacf51378876c4ed4aceb85 Mon Sep 17 00:00:00 2001 From: "sayurinana(vm)" Date: Fri, 12 Dec 2025 04:58:51 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=83=20docs:=20=E8=B0=83=E6=95=B4?= =?UTF-8?q?=EF=BC=8C=E5=87=86=E5=A4=87=E9=87=8D=E6=96=B0=E5=AF=B9=E8=AF=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- cache/1.md | 18 ++ cache/talk-about.md | 40 +++ {guide => docs}/01-自定义斜杠命令指南.md | 0 {guide => docs}/02-技能指南.md | 0 {guide => docs}/03-插件指南.md | 0 {guide => docs}/04-插件市场指南.md | 0 ...什么要更换到command+skill+专用处理程序.md | 245 ++++++++++++++++++ 7 files changed, 303 insertions(+) create mode 100644 cache/1.md create mode 100644 cache/talk-about.md rename {guide => docs}/01-自定义斜杠命令指南.md (100%) rename {guide => docs}/02-技能指南.md (100%) rename {guide => docs}/03-插件指南.md (100%) rename {guide => docs}/04-插件市场指南.md (100%) create mode 100644 docs/为什么要更换到command+skill+专用处理程序.md diff --git a/cache/1.md b/cache/1.md new file mode 100644 index 0000000..63bd358 --- /dev/null +++ b/cache/1.md @@ -0,0 +1,18 @@ +我想和你讨论一些东西，但在此之前，我要先向你提出一些要求，比如“我说的东西可能会比较口语化，你要分析我说的信息，理解其真实意图，最终目标，同时深度思考我的想法是否存在致命的错误、不足之处、多余的考虑、可以优化的地方、可以有多重选择达到同一效果的部分步骤”， +你能理解我的意思吗，首先我希望你对我前面提出的“比如”的这部分要求进行一些优化使其更周全更准确更清晰 + +我想要构建一套系统，其最终应该会包含一些文档和一些工具，这一套系统是要提供给用户使用为用户服务的， +我是应该先把具体的工具做出来，再根据工具写文档，再根据已有的文档提炼一个入口、入门指南， +还是应该先定好文档信息包括整套文档和快速指南，再把文档中所描述的工具实现出来， + +太好了，我需要的是“用户场景驱动”这种模式，更具体一点，我想做的事是：把 ai-agent-memory/ 目录下原本的提示词文档形式的指令体系，转换为Claude Code的commands+skills+处理过程封装为专用程序的形式， +还可以参看：docs/ 目录下是一些编写指南和一份需求分析文档， anthropic-agent-skills/ 目录下是anthropic官方提供的包含一些skills（仅有skills没有commands）的含有两个plugin的plugin marketplace本地目录范例， + +我认为需要封装的操作是一些流程与形式上的操作，以此减少不确定性并减少token污染减少不必要的LLM注意， +把核心的分析、思考、业务内容交给LLM不加限制竭尽所能尽情发挥， +这套系统开发好后我希望成品是3项： +- 一个可供用户快速上手且能引导用户根据需要进行深入了解的README.md +- 一个可以快速安装的插件市场（在README中提供快捷指令） +- 一套实现了目标程序系统的项目目录 +我希望的下发/分享方式是把这1个文档+2个目录打包为一个压缩包分享（先以此为暂定目标，当该体系经验证可用且高效后再考虑更好的形式：再把插件市场迁入远程仓库，把程序投放到一些包托管平台，便于快速安装，然后只需以网页或文档的形式分享README即可）， +@aide-requirements.md 是一个我原本暂定的细则文档，现在需要你根据我前述的需求，评估这个文档是否满足：仅以这一份文档为核心，辅以原 ai-agent-memory/ 和 docs/ 目录下的信息，开始实际开发任务，得到3项最终产出 diff --git a/cache/talk-about.md b/cache/talk-about.md new file mode 100644 index 0000000..deb1fcd --- /dev/null +++ b/cache/talk-about.md @@ -0,0 +1,40 @@ + --- + 完整协作框架： + + 第一阶段：发散解读（探索可能性） + + 针对你的输入，我不预设你是对的，而是： + - 提炼你字面表达的核心 + - 推测你可能真正想要的（多种解读） + - 补充你可能没想到但值得考虑的方向 + + 输出：多种可能的理解/方向，供你比对 + + --- + 第二阶段：方向推敲（收敛确认） + + 对每种可能的方向进行审视： + - 各自的优劣与适用场景 + - 潜在风险或隐藏代价 + - 是否真正匹配你的深层目标 + + 输出：帮你判断并确认正确的大方向 + + --- + 第三阶段：深度优化（细化落地） + + 方向确认后，针对选定方案： + - 逻辑漏洞与遗漏补全 + - 冗余部分精简 + - 具体步骤细化 + - 可替代的局部实现方式 + + 输出：经过深度打磨的完整方案 + + --- + 一句话总结这个协作模式： + + 你给线索 → 我展开可能性 → 共同确认方向 → 再深挖细节 + + --- + \ No newline at end of file diff --git a/guide/01-自定义斜杠命令指南.md b/docs/01-自定义斜杠命令指南.md similarity index 100% rename from guide/01-自定义斜杠命令指南.md rename to docs/01-自定义斜杠命令指南.md diff --git a/guide/02-技能指南.md b/docs/02-技能指南.md similarity index 100% rename from guide/02-技能指南.md rename to docs/02-技能指南.md diff --git a/guide/03-插件指南.md b/docs/03-插件指南.md similarity index 100% rename from guide/03-插件指南.md rename to docs/03-插件指南.md diff --git a/guide/04-插件市场指南.md b/docs/04-插件市场指南.md similarity index 100% rename from guide/04-插件市场指南.md rename to docs/04-插件市场指南.md diff --git a/docs/为什么要更换到command+skill+专用处理程序.md b/docs/为什么要更换到command+skill+专用处理程序.md new file mode 100644 index 0000000..d984ddb --- /dev/null +++ b/docs/为什么要更换到command+skill+专用处理程序.md @@ -0,0 +1,245 @@ +# 核心指引 + +## 一、问题背景 + +在AI辅助开发的实践中，存在几个普遍性问题： + +1. **信息过载**：每次交互都需要传递大量上下文，包括规则、流程、约束等，造成token消耗和注意力分散 +2. **不确定性累积**：自然语言描述的流程存在歧义，多次执行可能产生不同结果 +3. **重复劳动**：相似的操作模式反复出现，却每次都需要重新描述和执行 +4. **认知负担**：复杂流程的完整规则难以在单次对话中完整呈现和遵循 + +## 二、核心理念 + +### 2.1 渐进式披露 + +**原则**：信息按需加载，而非一次性全量呈现。 + +传统做法是在CLAUDE.md中堆积所有规则和流程说明，导致： +- 初始上下文臃肿 +- 大部分规则在当前任务中并不需要 +- 规则之间可能存在冲突或优先级不明 + +改进方向是将规则和流程封装为可调用的单元，仅在需要时触发加载。 + +### 2.2 确定性封装 + +**原则**：将可变过程转化为固定接口。 + +自然语言描述的操作存在解释空间，例如"更新状态记录"可能被理解为： +- 直接编辑CSV文件 +- 追加新行 +- 修改现有行 +- 重建整个文件 + +通过程序封装，将这种不确定性消除： +- 输入：明确的参数 +- 输出：确定的结果 +- 过程：固定的逻辑 + +### 2.3 关注点分离 + +**原则**：流程编排与具体执行分离。 + +- **Commands**：负责"做什么"和"按什么顺序做" +- **Skills**：负责"怎么做"的具体实现 + +这种分离使得： +- 流程调整不影响具体实现 +- 实现优化不改变流程结构 +- 各部分可独立演进 + +## 三、Commands的意义与原理 + +### 3.1 本质定位 + +Commands是**流程的触发器和编排器**。 + +它不执行具体操作，而是： +1. 定义一个完整流程的阶段划分 +2. 规定各阶段的执行顺序和转换条件 +3. 指明每个阶段应调用的Skills +4. 处理异常和分支情况 + +### 3.2 设计原理 + +Commands通过Markdown文件定义，包含： + +``` +命令名称 → 触发入口 +前置条件 → 执行门槛 +流程阶段 → 状态机定义 +阶段动作 → Skills调用指引 +异常处理 → 分支和恢复策略 +``` + +当用户调用一个Command时，AI获得的是一份**结构化的执行指南**，而非散落的规则片段。 + +### 3.3 价值体现 + +| 传统方式 | Command方式 | +|---------|------------| +| 每次描述完整流程 | 一次定义，多次调用 | +| 流程步骤可能遗漏 | 阶段明确，不易遗漏 | +| 异常处理临时决定 | 预设异常处理策略 | +| 难以追踪执行进度 | 状态机明确当前位置 | + +## 四、Skills的意义与原理 + +### 4.1 本质定位 + +Skills是**操作的标准化封装**。 + +它将一类具体操作： +1. 抽象为统一的接口 +2. 隐藏内部实现细节 +3. 提供确定性的输入输出 +4. 减少执行过程中的信息噪声 + +### 4.2 设计原理 + +Skills通过SKILL.md定义接口，通过脚本实现逻辑： + +``` +接口定义（SKILL.md）： + - 功能说明 + - 输入参数 + - 输出格式 + - 使用示例 + +实现脚本（*.py/*.sh）： + - 参数解析 + - 业务逻辑 + - 结果输出 + - 错误处理 +``` + +AI只需要知道"调用什么、传什么参数、期望什么结果"，无需关心内部如何实现。 + +### 4.3 价值体现 + +| 传统方式 | Skill方式 | +|---------|----------| +| 直接操作文件/命令 | 调用封装接口 | +| 输出信息冗长 | 输出精简有效 | +| 错误处理不一致 | 统一错误格式 | +| 操作结果不确定 | 结果格式固定 | + +## 五、协作模式 + +### 5.1 调用关系 + +``` +用户 → Command → 流程阶段 → Skill → 脚本 → 结果 + ↓ ↓ ↓ + 加载流程 状态流转 执行操作 +``` + +### 5.2 信息流向 + +**向下传递**： +- Command向Skill传递必要的上下文参数 +- Skill向脚本传递具体的操作参数 + +**向上返回**： +- 脚本返回执行结果（成功/失败/数据） +- Skill返回格式化的结果 +- Command根据结果决定下一步流转 + +### 5.3 职责边界 + +| 层级 | 职责 | 不负责 | +|-----|------|-------| +| Command | 流程编排、状态管理、异常策略 | 具体操作实现 | +| Skill | 接口定义、参数校验、结果格式化 | 流程决策 | +| 脚本 | 具体逻辑执行 | 业务语义理解 | + +## 六、设计原则 + +### 6.1 最小暴露原则 + +只暴露必要的接口和参数，隐藏实现细节。 + +**反例**：要求AI理解CSV文件格式并手动编辑 +**正例**：提供`update_status(task_id, status)`接口 + +### 6.2 失败友好原则 + +预设失败场景的处理策略，而非依赖临时判断。 + +**反例**：遇到错误时"请自行判断如何处理" +**正例**：定义明确的错误码和对应的恢复动作 + +### 6.3 幂等性原则 + +相同输入产生相同结果，重复执行不产生副作用。 + +**反例**：每次执行都追加记录，导致重复数据 +**正例**：基于唯一标识更新，存在则更新，不存在则创建 + +### 6.4 可观测原则 + +执行过程和结果应当可追踪、可验证。 + +**反例**：操作完成后无任何反馈 +**正例**：返回结构化的执行报告，包含操作内容和结果 + +## 七、与传统方式的对比 + +### 7.1 上下文管理 + +| 方面 | 传统方式 | Commands + Skills | +|-----|---------|-------------------| +| 规则存放 | CLAUDE.md堆积 | 分散到各Command/Skill | +| 加载时机 | 对话开始全量加载 | 调用时按需加载 | +| 更新维护 | 修改单一大文件 | 修改对应模块 | + +### 7.2 执行过程 + +| 方面 | 传统方式 | Commands + Skills | +|-----|---------|-------------------| +| 流程遵循 | 依赖AI记忆和理解 | 状态机强制约束 | +| 操作执行 | 自然语言描述 | 程序化调用 | +| 结果反馈 | 格式不固定 | 结构化输出 | + +### 7.3 可维护性 + +| 方面 | 传统方式 | Commands + Skills | +|-----|---------|-------------------| +| 流程修改 | 修改描述文本 | 修改状态机定义 | +| 操作优化 | 重写描述 | 修改脚本实现 | +| 问题定位 | 回溯对话历史 | 检查对应模块 | + +## 八、适用场景判断 + +### 8.1 适合封装为Command的场景 + +- 包含多个有序阶段的复杂流程 +- 需要状态追踪和异常恢复 +- 会被重复执行的标准化流程 +- 涉及多个Skills协作的编排任务 + +### 8.2 适合封装为Skill的场景 + +- 单一职责的具体操作 +- 输入输出可明确定义 +- 执行逻辑相对固定 +- 需要减少信息噪声的操作 + +### 8.3 不适合封装的场景 + +- 一次性的探索性任务 +- 高度依赖上下文判断的决策 +- 需要灵活调整的创意工作 +- 简单到不值得封装的操作 + +## 九、总结 + +Commands和Skills体系的核心价值在于： + +1. **降低认知负担**：将复杂流程分解为可管理的单元 +2. **提高执行确定性**：用程序逻辑替代自然语言描述 +3. **减少信息噪声**：只传递必要信息，隐藏实现细节 +4. **增强可维护性**：模块化设计便于独立演进 + +这不是要限制AI的能力，而是为AI提供更清晰的执行框架，使其能够更专注于真正需要智能判断的部分，而非在重复性的流程遵循上消耗注意力。