Maoclaw V0.1 Known Limitations

# 猫爪 v0.1 已知限制

Status: Draft  
Audience: Trial users, product, engineering, support, operations  
Companions: [maoclaw-v0.1-trial-release-plan.md](maoclaw-v0.1-trial-release-plan.md), [maoclaw-v0.1-support-scope.md](maoclaw-v0.1-support-scope.md), [maoclaw-v0.1-faq.md](maoclaw-v0.1-faq.md)

## 1. 文档目的

本文档用于明确猫爪 v0.1 小范围试用版的已知限制，避免对外承诺超过当前真实能力。

原则：

- 已知限制必须可读、可理解、可被支持团队引用
- 已知限制不是失败，而是首版边界的一部分
- 如果一项能力无法稳定保证，就必须进入本文件

## 2. 总体声明

猫爪 v0.1 是一个**小范围试用版**。

因此，本版本更关注：

- 核心工作流是否可用
- 安装和启动是否顺畅
- 试用反馈是否可回收

而不是追求：

- 对所有历史工作流完全兼容
- 对所有外部扩展生态完全兼容
- 对所有自动化接入语义完全稳定

## 3. 兼容性限制

### 3.1 不是 strict drop-in replacement

猫爪 v0.1 不能宣称自己已经严格覆盖所有历史 CLI、RPC 与自动化工作流。

影响：

- 某些 CLI 行为可能存在差异
- 某些 RPC 事件或语义可能存在差异
- 某些 SDK 接入代码不能直接无修改复用

建议：

- 把猫爪 v0.1 视为可试用产品，而不是零改造替换件

### 3.2 SDK 兼容有限

当前版本不承诺完整 SDK contract parity。

影响：

- 嵌入式接入方可能需要适配层
- 与上游 TS SDK 形态严格对齐的场景不建议在 v0.1 上直接上线

建议：

- 首批试用尽量优先 CLI 用户
- SDK 深度接入放到 v0.2 之后单独评估

### 3.3 JSON/RPC 兼容有限

当前版本支持基础 RPC 模式，但不承诺所有命令语义、事件顺序和行为细节完全与上游一致。

影响：

- IDE / 自动化客户端可能需要针对当前实现做适配
- 复杂 agent 控制流程可能出现行为差异

建议：

- 首批试用仅开放给可接受接口变动的集成方
- 把 RPC 接入视为试验性能力

### 3.4 Slash command 完整性有限

交互式命令主路径存在，但不承诺所有 slash command 都达到严格对齐状态。

影响：

- 高频命令外的一些命令可能有行为差异
- 某些命令的 UX 细节可能与用户预期不同

建议：

- 对外重点展示高频稳定命令
- 把长尾命令列入内部测试而非外部卖点

## 4. 扩展限制

### 4.1 扩展运行时可用，但不等于扩展生态成熟

猫爪 v0.1 支持基础扩展运行时，但不承诺完整第三方扩展生态兼容。

影响：

- 某些现有扩展可能部分可用、部分不可用
- 某些复杂扩展的命令行参数透传可能不完善

建议：

- 首批试用优先使用官方或内部验证过的扩展
- 把复杂第三方扩展列为“逐个验证”范围

### 4.2 生命周期 hook parity 不完整

扩展 hook 的调用覆盖、顺序和细节仍可能存在差异。

影响：

- 强依赖生命周期 hook 的扩展可能出现行为漂移

建议：

- 试用期不要把复杂 hook 依赖场景作为核心卖点

### 4.3 历史插件生态不在首版承诺中

猫爪 v0.1 不承诺与所有历史插件生态直接兼容。

影响：

- 不能直接把现有第三方插件兼容写入销售或试用说明

建议：

- 如需兼容，逐个插件建立验证列表

## 5. 平台与环境限制

### 5.1 首版以 macOS 为主

虽然项目具备跨平台基础，但首版主支持平台是 macOS。

影响：

- Linux / Windows 的表现可能未达到同等稳定度
- 文档、演示和支持路径优先围绕 macOS 构建

建议：

- 首批试用尽量选择 macOS 用户

### 5.2 终端环境差异会影响体验

不同 shell、终端模拟器、字体和输入法环境可能影响交互表现。

影响：

- 补全、键位、渲染和滚动体验可能有差异

建议：

- 首批试用优先使用团队验证过的终端环境

### 5.3 企业环境覆盖有限

首版不承诺覆盖所有企业代理、离线、锁定环境。

影响：

- 某些网络受限环境可能需要手工配置
- 某些安装流程可能需要额外说明

建议：

- 企业试用前先做环境预检查

## 6. 安装与升级限制

### 6.1 安装脚本优先保障主路径

`install.sh` 是首版主安装路径，但不承诺所有异常安装历史都能自动修复。

影响：

- 历史残留的 `pi` 安装状态可能需要人工处理
- PATH 与 shell 配置问题可能需要手动排查

建议：

- 试用期配套提供安装排障说明

### 6.2 保留 `pi` 命令会带来品牌与技术标识并存

首版品牌名是猫爪，但命令仍为 `pi`。

影响：

- 用户可能看到“猫爪”和 `pi` 同时出现
- 需要文档明确说明这不是安装错误

建议：

- 在 Quick Start 与 FAQ 中主动解释

### 6.3 升级 / 回滚路径需谨慎验证

安装器支持迁移和并存，但复杂历史环境中仍可能出现边缘问题。

影响：

- 从 TypeScript `pi` 升级过来的用户更容易遇到问题

建议：

- 对外先限定已验证的迁移路径

## 7. Provider 与认证限制

### 7.1 首版 Provider 范围有限

首版重点支持 Anthropic、OpenAI、Gemini、Azure OpenAI。

影响：

- 其他 provider 不应作为对外默认能力宣传

### 7.2 认证与密钥配置体验仍需简化

尽管已有基础能力，但不同 provider 的配置体验可能仍有差异。

影响：

- 首次使用者可能仍需要查看文档才能完成配置

建议：

- Quick Start 中只写最短成功路径

## 8. 会话与数据限制

### 8.1 会话主路径可用，但不承诺所有高级场景成熟

当前版本重点支持保存、继续、恢复与基础分支。

影响：

- 一些高级迁移、复杂分支或未来 V2 存储能力不应视为首版成熟能力

### 8.2 不承诺 V2 存储层默认成熟可用

仓库中已存在更后续阶段的模块与文档规划，但这些不是猫爪 v0.1 的默认交付范围。

影响：

- 不能把 V2 产品层功能混入首版营销

建议：

- 对外仅描述当前已验证的会话能力

## 9. 文档与沟通限制

### 9.1 品牌名与兼容命令会并存

当前对外品牌统一为猫爪 / maoclaw，但兼容命令仍保留为 `pi`。

影响：

- 用户会同时看到品牌命名和兼容命令
- 如果解释不清，会误以为安装异常

建议：

- 在首页、Quick Start、FAQ 中反复解释 `pi` 是兼容命令而不是旧产品入口

### 9.2 某些历史文档反映的是工程状态，不是对外产品口径

例如 parity、认证、架构文档主要服务研发，不适合直接作为外部产品说明。

影响：

- 若直接给客户看，会混淆“能用”和“完全兼容”的概念

建议：

- 对外只使用经过产品化整理的试用文档

## 10. 支持与运营限制

### 10.1 首版支持能力有限

试用期的支持重点应放在：

- 安装问题
- provider 配置问题
- 工具调用主路径问题
- 会话恢复问题

不建议首版承诺：

- 复杂定制开发支持
- 大规模企业接入支持
- 全量插件兼容支持

### 10.2 反馈处理节奏需要明确

试用版一定会暴露问题，因此必须设定：

- 反馈入口
- 响应级别
- 已知问题更新机制
- 是否进入 hotfix 的判断规则

## 11. 不建议对外说的话

在猫爪 v0.1 阶段，不建议对外使用以下表述：

- “完全替代所有历史工作流”
- “完全兼容所有历史插件”
- “可无缝替换所有现有 SDK 集成”
- “所有插件都可直接复用”
- “所有平台都同等成熟”
- “这是正式商用稳定版”

## 12. 推荐对外说法

建议优先使用以下表述：

- “猫爪 v0.1 是小范围试用版”
- “适合早期开发者与设计伙伴客户试用”
- “兼容 Pi 工作流主路径”
- “优先支持 macOS 与终端试用体验”
- “欢迎反馈高频使用问题”

## 13. 何时从已知限制中移除一项

只有当以下四项都满足，某项限制才应从本文件中移除：

1. 功能已实现
2. 回归已覆盖
3. 文档已更新
4. 支持团队知道如何处理相关问题

## 14. 一句话总结

猫爪 v0.1 已知限制的核心原则是：

> **首版不是要假装没有问题，而是要清楚说明哪些问题已经解决、哪些问题暂不承诺、哪些问题正在试用中验证。**