托管你的项目维护
类型：维护案例。 这不是一份“如何改仓库”的教程，而是一条从反馈到回归证据的真实维护主线：让下一位 Agent 能理解发生过什么、为什么这样修、怎样确认没有复发。
项目维护最容易失控的地方，不是改动本身，而是“修好了”没有定义。一个反馈如果只留下补丁，下一次同类问题仍然会重新发生；如果把一次局部修复直接扩大成新的公开契约，又可能给所有用户增加不必要的负担。
这次维护要解决什么
反馈指出：公开安装说明把 Agent 应该执行的安装边界写得不够准确，用户容易把个人知识写进 OKS 源码仓库，也无法判断安装完成后哪些能力真的可用。
维护目标不是继续堆叠说明，而是让公开承诺与实际能力对齐：
- Agent 能按照上游安装 Skill 完成安装和实例隔离；
- 用户能看到实例位置、可用能力和审核边界；
- 文档不会把可选集成、实验能力或未验证结果写成默认能力；
- 同类反馈下，下一位 Agent 能沿着同一条检查路径复现并验收。
一条可回归的维护记录
1. 人先定义反馈和“修好”
人负责说明哪里不对，以及什么结果才算修好：
- 哪一句公开承诺会让用户误解；
- 哪个行为必须保持不变；
- 是否允许扩大 CLI、Skill 或安装包的公开契约；
- 需要看到哪些证据，才接受这次修复。
这里的“修好”不是“页面看起来更完整”，而是公开文档、Skill、CLI 能力和打包边界能够互相对上。
2. Agent 复现、定位并提出最小改动
Agent 负责把反馈变成可检查的事实：
- 复现用户看到的提示、错误或断裂的路径；
- 对照当前 Skill、CLI、测试和打包内容，确认事实来源；
- 区分“实现缺失”“文档承诺过度”和“可选能力没有安装”；
- 给出最小修复方案，并说明它会影响哪些用户和公开接口。
Agent 可以提出多个候选方案，但不能自行决定把维护问题升级成新的产品能力。
3. 人决定是否扩大公开契约
维护者需要明确批准边界：
- 只修正文档和 Skill；
- 增加一个确实有独立语义的能力；
- 将能力保持为 maintainer-only；
- 或者确认当前行为正确，只补充失败说明和回归检查。
这个门禁保护的是项目的长期稳定性：一次反馈不应自动变成一项永久公开承诺。
4. 留下修复、证据和可复用规则
一次维护闭环至少留下四类结果：
| 结果 | 作用 |
|---|---|
| 修复 | 公开页面、Skill 或实现与批准的契约一致 |
| 验证证据 | 说明复现、测试、构建或真实试用分别证明了什么 |
| 边界 | 记录哪些能力仍未安装、未运行或未被证明 |
| 维护规则 | 让下一位 Agent 知道同类反馈应先检查什么 |
本案例沉淀的规则是：文档不是装饰，而是 Agent 会执行的契约；修改公开承诺前，必须同时核对运行能力、分发边界和回归验证。
人和 Agent 各自负责什么
| 人 | Agent |
|---|---|
| 描述问题和验收标准 | 复现问题并整理证据 |
| 决定是否扩大公开契约 | 检查 Skill、CLI、测试和打包边界 |
| 批准最小改动 | 实施修改并报告影响面 |
| 判断结果是否可接受 | 运行回归检查并保留失败状态 |
Agent 不能用“测试通过”替代人的产品判断；人也不需要亲自拼接每个检查步骤。
本次结果与未验证项
已完成的维护结果：
- 安装页改为直接引用上游 main 的安装 Skill；
- 公开文档改为由 Agent 执行安装、实例隔离和能力检查；
- 安装 Skill 明确区分初始化、Skill 刷新、可选能力和审核流程；
- 文档与 Skill 的一致性检查已纳入回归验证。
仍需单独验证的内容：
- GitHub Pages 的最终桌面与移动端渲染；
- 不同 Agent Host 对上游 Skill 的实际发现和执行；
- 可选 Provider 在具体机器上的安装状态；
- 本次修改是否已经合并到上游 main。
这些项目保持“未验证”，不会因为页面更新或自动化测试通过就被改写成完成。