work-ally 0.2.0-alpha.1

package/docs/planning/SPEC-skill-first-capability-packaging.md

@@ -0,0 +1,338 @@
+# Skill-First Capability Packaging
+
+更新时间：2026-03-21  
+状态：Draft / Exploration  
+Owner：Ally  
+相关文档：
+- `docs/product-spec-standard.md`
+- `docs/architecture/codex-feishu-bridge-proposal.md`
+- `docs/implementation/work-ally-implementation-guide.md`
+- `skills/`
+- `.research/nanoclaw/CONTRIBUTING.md`
+- `.research/openclaw/skills/skill-creator/SKILL.md`
+
+## 1. Summary
+
+这份 spec 要回答的不是“现在立刻把多少代码搬成 skill”，而是先把 `work-ally` 的一个长期产品方向收清楚：
+
+> 对于新增能力，默认先判断它是否应该做成一个 Skill 包，而不是继续把逻辑长进中间层核心。
+
+这里的 Skill 不是一段孤立提示词，而是一个能力包：`SKILL.md` 加上可选的 `scripts/`、`references/`、`assets/`。它更适合承接“AI 遇到特定任务时怎么做”的方法、模板、辅助脚本与领域工作流，而不是承接桥接主链路本身。
+
+这次 spec 的首要目标有两个：
+
+1. 固定 `Core / Hybrid / Skill` 三分法，作为今后新增能力的默认判断模型。
+2. 固定 `skill-first` 产品原则：新增 capability 若可作为 Skill 包成立，就不应优先进入 bridge / internal 核心。
+
+这次不直接推进已有能力的大规模外迁。旧能力往外迁，另立后续专题，避免一次改动过大影响稳定性。
+
+## 2. 背景
+
+### 2.1 当前问题不是“会不会做功能”，而是“功能往哪里长”
+
+`work-ally` 经过多轮 bridge core thinning 之后，长期方向已经越来越明确：
+
+- core 只负责忠实桥接
+- 中间层只补官方 Codex 与真实协作场景之间的缝隙
+- 不继续把产品做成第二套任务系统或第二套 agent 脑
+
+但当前仍缺一条明确的新增能力准则：
+
+- 某个能力到底应该进 bridge core？
+- 还是应该进 desk 资产？
+- 还是其实更适合做成 Skill 包？
+
+如果这条准则不先拍板，后续每次加 feature 都很容易重新把中间层做厚。
+
+### 2.2 官方 Codex 的 Skill 模型已经给了正确启发
+
+官方 Codex 的 Skills 本身就是一种“能力包”机制，而不是只塞一段常驻提示词。一个 Skill 可以包含：
+
+- `SKILL.md`
+- `scripts/`
+- `references/`
+- `assets/`
+
+这说明 Skill 更适合承接：
+
+- 特定任务的 workflow
+- 可复用模板
+- 辅助脚本
+- 领域知识与参考资料
+
+也就是说，它天然适合作为 `work-ally` 的“内容工作流外挂层”。
+
+### 2.3 竞品给出的方向高度一致
+
+从 research 目录里的参考实现看，方向基本一致：
+
+- NanoClaw 的态度非常激进：新 feature、capability、compatibility、enhancement 默认不直接进核心源码，而是做成 skills。
+- OpenClaw 的实践更成熟：它把很多渠道与领域能力组织成独立 skills，并明确把 skill 视为模块化、自包含、可组合的能力包。
+
+这两者虽然程度不同，但都在强调同一件事：
+
+> 主产品保持极简，把变化快、个性化强、方法论导向的能力外置。
+
+### 2.4 `work-ally` 其实已经有这条路的雏形
+
+当前仓库并不是从 0 开始：
+
+- `skills/archive-reader/`
+- `skills/memory-digest/`
+- `skills/product-spec/`
+
+另外，灯塔文档和 implementation guide 里都已经写过类似判断：`archive-reader`、`memory-digest` 这类机制能力更适合落成 skills 或等价装配点。
+
+因此，这次 spec 更像是把已有直觉、零散实践和长期边界，正式收口成一个产品合同。
+
+## 3. 问题定义
+
+当前如果不明确建立 `skill-first` 准则，会持续出现 4 类问题：
+
+### 3.1 新能力默认继续长进中间层
+
+即使某个能力本质上只是“AI 在某类任务里该如何工作”，实现时也很容易顺手长到 bridge / internal 里，导致核心越来越厚。
+
+### 3.2 内容工作流和桥接合同混在一起
+
+路由、审批、恢复、状态真相，和摘要提炼、模板生成、排查方法、本地脚本，这些本来是不同层级的东西；一旦混住，就会让 bridge 丧失清晰边界。
+
+### 3.3 用户定制空间被核心实现绑死
+
+如果能力都长在核心里，用户要么接受整包复杂度，要么只能 fork 主产品改代码；这不利于让用户按项目或按角色做差异化能力包。
+
+### 3.4 后续维护重心会继续落在“守着大 core”
+
+真正高成本的不是现在这一次改多少代码，而是未来每加一个 feature，都要在 bridge / internal 里再拧一轮产品语义、测试和恢复路径。
+
+## 4. 目标 / 非目标
+
+### 4.1 目标
+
+1. 定义 `Core / Hybrid / Skill` 三分法，作为新增能力默认判断模型。
+2. 明确 `skill-first` 原则：新增 capability 若可以作为 Skill 包成立，不优先长进 core。
+3. 固定 `work-ally` 的第一阶段 Skill 包边界：依赖官方 Codex Skill 机制，不自造第二套插件平台。
+4. 明确第一阶段的信任与分发边界：先做仓库内 / 自管 / 可审计的 Skill，不做远程 market。
+5. 列出当前最适合试点 Skill 化的能力候选，为后续专题提供输入。
+6. 把这条原则同步回核心产品文档与项目纪律，避免它只停留在一次聊天里。
+
+### 4.2 非目标
+
+1. 这次不直接迁移已有能力到 Skill。
+2. 这次不承诺上线远程 Skill marketplace、在线安装或自动拉取机制。
+3. 这次不为 Skill 再造一套独立 runtime / registry / sandbox 平台。
+4. 这次不修改 bridge 主链路的稳定行为。
+5. 这次不把所有能力一股脑地解释成 Skill。
+
+## 5. 产品定义与用户路径
+
+### 5.1 一句话定义
+
+> `work-ally` 的长期方向是：bridge core 负责稳定桥接合同，变化快、定制性强、方法论驱动的能力优先做成 Skill 包。
+
+### 5.2 这份 spec 的主要使用者
+
+这份 spec 主要不是给终端用户看的，而是给：
+
+- 产品经理
+- 工程维护者
+- 后续 feature owner
+
+他们在新增能力之前，必须先回答：这件事到底应该放在哪一层。
+
+### 5.3 新增能力的默认路径
+
+以后当有人提出一个新能力时，默认先走下面这个判断路径：
+
+1. 它是不是 bridge contract 的一部分？
+2. 如果不是，它是不是只是在回答“AI 遇到某类任务时怎么做”？
+3. 如果是，它能否作为 `SKILL.md + scripts/references/assets` 的能力包独立成立？
+4. 如果能，默认不优先改 bridge / internal 核心，而是优先设计为 Skill 或 Hybrid。
+
+### 5.4 对用户意味着什么
+
+这条方向不是为了让用户学习更多新概念，而是为了让最终产品更轻：
+
+- 默认核心更稳定
+- 非主链路能力更容易定制
+- 不需要的人不必继承整包复杂度
+
+## 6. 机制设计
+
+### 6.1 三分法定义
+
+#### A. Core
+
+Core 只承接“没有它，桥就不成立”的能力。
+
+典型包括：
+
+- Feishu 收发与路由
+- approval / user-input gate
+- active turn steer
+- recovery / final redelivery
+- same-machine handoff
+- scheduler 的触发、占位、去重与状态记录
+
+判断标准：
+
+- 如果拿掉它，bridge 主链路就不再成立
+- 或者产品无法继续诚实表达运行真相
+
+那么它必须留在 core。
+
+#### B. Hybrid
+
+Hybrid 指的是：
+
+- 触发、调度、通知、写回、失败补偿留在 core
+- 具体内容生成、提炼规则、模板和辅助脚本放进 Skill 包
+
+这类能力既和 bridge 运行态有关，又包含明显的内容工作流。
+
+当前最典型的候选就是：
+
+- `memory-digest`
+
+#### C. Skill
+
+Skill 只承接“遇到某类任务时 AI 应该怎么工作”的能力包。
+
+它更适合放：
+
+- 方法论
+- 工作流
+- 模板
+- 领域参考资料
+- 辅助脚本
+- 可选资产
+
+它不应该直接承接：
+
+- 路由真相
+- 审批真相
+- 会话恢复真相
+- 交付补偿真相
+
+### 6.2 Skill 包定义
+
+在 `work-ally` 里，Skill 采用官方 Codex 的能力包心智，不再把 Skill 理解成“一个额外提示词文件”。
+
+一个 Skill 包至少包含：
+
+- `SKILL.md`
+
+可按需包含：
+
+- `scripts/`
+- `references/`
+- `assets/`
+
+因此，Skill 适合表达的是“按需加载的机制能力”，而不是“主身份”或“常驻人格”。
+
+### 6.3 第一阶段挂载边界
+
+第一阶段坚持 KISS：
+
+- 直接复用官方 Codex Skill 机制
+- `work-ally` 不自造第二套 Skill runtime
+- `work-ally` 不自造远程插件市场
+- `work-ally` 不为 Skill 再做独立权限模型
+
+第一阶段只承认两类可信来源：
+
+1. 仓库内随产品分发的内置 Skill
+2. 用户自己管理、自己承担后果的本地自管 Skill
+
+也就是说，第一阶段的重点不是“让用户随便装很多东西”，而是先把边界拍板：
+
+> 什么该进 core，什么该作为 Skill 包挂进来。
+
+### 6.4 新增能力的评审规则
+
+从这份 spec 开始，后续新增 capability 的 spec，至少应显式回答一次：
+
+- 这件事为什么必须进 core？
+- 如果不进 core，是否可以作为 Skill？
+- 如果不能纯 Skill，是否应设计为 Hybrid？
+
+如果这三个问题没有回答清楚，不应直接把能力写进 bridge / internal。
+
+### 6.5 第一批候选范围
+
+这次 spec 只给出候选，不直接迁移实现。
+
+#### 最适合先试点的候选
+
+1. `archive-reader`
+   - 最接近纯 Skill
+2. `memory-digest`
+   - 最适合做 Hybrid
+3. 技术客服排查能力包
+   - 未来非常适合作为项目级 Skill
+
+#### 明确不作为第一批试点的能力
+
+- Feishu 路由
+- approval gate
+- recovery / steer
+- handoff
+- runtime transport
+- 状态账本与最终态确认
+
+这些能力属于 bridge contract，本身就不应外包给 Skill。
+
+### 6.6 对代码规模的现实预期
+
+这次方向的核心收益，不是立刻把总代码“砍掉很多”。
+
+更真实的收益是两层：
+
+1. 中短期内，有机会把 bridge 里一部分内容工作流逻辑往外抽薄。
+2. 长期内，阻止新增能力继续无边界地长进 core。
+
+因此，Skill-first 的主要价值是：
+
+- 降低复杂度增长率
+- 降低未来功能接入成本
+- 提高用户定制能力
+
+而不只是一次性的 LOC 缩减。
+
+## 7. 验收标准
+
+这份 spec 进入可用状态，至少要满足：
+
+1. `Core / Hybrid / Skill` 三分法定义清楚，没有互相打架。
+2. 明确写清这次不迁移已有能力，只影响后续新增能力的准入思路。
+3. 明确写清第一阶段不做远程 Skill market，不自造第二套插件平台。
+4. 明确列出第一批候选与明确不迁移的主链路能力。
+5. 项目级核心文档已同步回写 `skill-first` 原则，而不是只留在 spec 里。
+6. 后续新增 capability 的评审流程，已经包含“为什么不是 Skill / 为什么不是 Hybrid”的问题。
+
+## 8. 风险 / 假设 / 待决问题
+
+### 8.1 风险
+
+- 如果把 Skill-first 理解成“所有东西都外置”，会伤害主链路稳定性。
+- 如果只写理念、不写评审规则，后续 feature 仍会照样长进 core。
+- 如果第一阶段就追求远程 market，会把中间层重新做厚。
+
+### 8.2 假设
+
+- 官方 Codex Skill 机制会继续作为稳定基础，不需要 `work-ally` 自己重造一层。
+- 用户真正需要的是定制能力，而不是一个更重的插件平台。
+- `work-ally` 的长期目标仍然是忠实桥接，而不是功能越做越全。
+
+### 8.3 待决问题
+
+1. 第一阶段是否需要给 assistant desk 明确一个“自管 product skills”目录，还是先只使用仓库内置 skills？
+2. `memory-digest` 未来的 Hybrid 收口，应先从 prompt / parse / references 外提开始，还是先定义统一 routine-skill contract？
+3. 技术客服类能力包，未来是否按项目级 skill 分发，还是按 assistant 角色级 skill 分发？
+
+## 9. 建议的后续顺序
+
+1. 先把这份探索型 spec 收口，并同步 `PRODUCT.md`、`README.md`、`AGENTS.md`、`DASHBOARD.md`。
+2. 从这之后，对所有新增 capability 启用 `skill-first` 评审规则。
+3. 等边界稳定后，再单独立专题处理“已有能力外迁”。
+4. 第一批试点优先考虑：`archive-reader` 与 `memory-digest`。