Roadmap
这份路线图默认你已经把 Ageniti 定位成“给 Agent 使用的应用 SDK”。
目标不是继续往 agent orchestration 扩张，而是把采用门槛、发布体验和升级信心补强。
P0 必做
这些是接下来最值得优先补齐的缺口。
1. 端到端接入路径
一个新团队应该能在不阅读 SDK 内部实现的情况下，从安装一路走到真实宿主接入。
目标结果：
- 安装包
- scaffold 一个 host starter
- 本地跑通一个 action
- 接进一个真实 host
- 导出 docs 和 manifest
- build 出可交付 bundle
验收标准：
- 至少有一条文档化路径能在 10 分钟内跑通
- 至少有一条路径覆盖已有应用接入
- 至少有一条路径覆盖 host-oriented starter
2. 完整新项目创建流程
现在的 init 更适合给已有项目加 Ageniti 入口，但对新项目用户还不够顺。
目标结果：
- 增加
ageniti create <template> <name> - 生成
package.json - 生成安装说明或 bootstrap 命令
- 生成一个跑起来后下一步非常明确的 starter
验收标准：
- 新目录可以不靠手写 setup note 就跑起来
- 生成的 README 会告诉用户如何验证成功
3. 面向宿主的集成指南
现在已经有 examples 和 starters，但还需要更贴近生产接入的文档。
优先级：
- OpenAI Responses host
- AI SDK route handler
- MCP desktop host
- HTTP gateway wrapper
验收标准：
- 每份指南都讲清 auth 边界
- 每份指南都讲清高风险 action 的过滤策略
- 每份指南都讲清哪些逻辑属于 host，哪些属于 Ageniti app
P1 应做
这些增强会显著提升信任感和长期维护体验。
1. Compatibility story
采用 SDK 的团队会非常在意升级时什么会坏。
目标结果：
- 明确的 action versioning 指南
- deprecation 策略
- CI 中的 manifest diff 示例
- contract 变更的 release notes 指引
验收标准：
- 开发者能区分 additive、risky 和 breaking change
- reviewer 能在 publish 前看到 contract drift
2. 更强的发布审查工具
SDK 应该帮助维护者看清“哪些能力正在变成 public surface”。
目标结果：
- surface exposure report
- 更聚焦风险的 lint
- 更完整的 publish checklist
- 自动生成“哪些 action 会进入哪些 surface”的摘要
验收标准：
- 维护者不需要手读源码，也能 review public exposure
3. 更好的 operator 调试体验
真实宿主接入失败时，团队需要更快定位原因。
目标结果：
- 更清晰的 error taxonomy
- invocation replay 模式
- artifact inspection 示例
- 针对常见 host integration 失误的 doctor 检查
验收标准：
- 常见接入失败能得到直接建议
- logs 和 envelope 足够支撑第一轮排查
P2 可做
这些适合在接入路径和信任体系稳定以后继续增强。
1. 更完整的 starters
- 更强的 README
- 更真实的 sample services
- 可选 TypeScript 版本
- 面向不同 host 的 env 示例
2. 更丰富的文档导航
- 单独的 host integration docs hub
- 单独的 shipping / upgrade safety docs hub
- 按用户类型推荐阅读路径
3. 更适合展示的 demo packaging
- reference repo
- walkthrough 演示
- 带最终输出截图的 hosted docs 示例
推荐执行顺序
- 先补完整的一条 adoption path。
- 再给新项目用户增加
create。 - 把 host-specific guide 写成真正的生产接入文档。
- 补强 compatibility 和 release review。
- 最后继续增强 debugging 和 diagnostics。
结论
Ageniti 下一阶段最需要的不是“更多框架能力”。
而是：
- 更容易采用
- 更安全地发布
- 更清晰的升级路径
- 更扎实的宿主接入指南
这些能力，才会让一个“已经可用的 SDK”真正变成“值得信任的 SDK”。