第三方 App 开发指南
本指南介绍如何使用 Agent Core 的公开接口开发 App，包含 API、接入示例、Skill 和 App 资料维护说明。英文版本从 English 开始，各页对应同目录的 *.en.md。
Agent Core 通过公开接口接入应用，可配合不同的服务框架、数据库、模型供应商和前端使用。
API 参考也是这套开发文档的一部分：API 首页、Core、Support、Kit。本指南解释如何组合这些接口和承担应用责任；接口签名、参数、返回、异常以对应 API 页为准。
从要完成的任务开始
先看工作机制图解，了解总体协作、任务与节点的区别、工作流推进、模型与工具调用时序，以及 App 知识回答示例。
先提供一个 ChatProvider，再调用 new ModelRunner({ provider }).invoke('你好')。Core 自己提供普通文本路径和默认运行设置，Support 与 Kit 都是可选项。工具、上下文处理、持久化和复杂编排在需要时逐步接入。
| 要完成的事 | 推荐入口 |
|---|---|
| 从空目录创建可运行的 Agent App | 创建应用 |
| 安装到已有项目、配置模型连接 | 安装与接入 |
| 生成一次回复 | 模型调用 |
| 集中声明工具、授权、执行并回传结果 | 工具接入 |
| 理解原始模型流与完整交付的区别 | 流式边界 |
| 编排条件循环和多阶段任务 | 注册与编排 |
| 控制上下文长度与压缩 | 上下文策略 |
| 根据已有资料生成并检查答案 | 知识资料、知识回答合同 |
| 处理用户材料与持久化 | 材料边界、记忆与持续积累 |
| 接入日志、取消和失败处理 | 交付与运维 |
| 核验完整接入 | 接入检查 |
局部接入方式见 示例，应用数据字段设计见 记录示例。人工准备和迭代见 维护手册，编码 Agent 的共用流程与 Skill 见 Agent 辅助开发。这些资产不会被库自动扫描、安装、发布或写入数据库。
三类接口如何协作
Core 拥有执行服务及调用／回调合同，例如工作流状态提交、模型调用预算、工具输入→执行→输出和真实调用回执。Support 帮 App 构造这些调用和被调度实现。Kit 由 App 自主选择，拥有自己的局部业务模型和规范。
Support 是接入支持的统一命名空间，内部包含多个模块。单个可选能力模块称一个 Kit；多个 Kit 由 /kits 汇总。一个 Kit 内部可以有自己的辅助函数和通用工具。
App 的鉴权、存储、资料加载和运行配置
→ Support 装配模型与上下文
→ Core 执行已登记的工作流、模型调用和工具
→ App handler 按需调用 Knowledge / Answering / Presentation 等 Kit
→ App 检查并交付结果模型提出的名字、参数、结论都不是鉴权、持久化授权或执行回执。App 可以不用某个 Kit，但仍须遵守实际使用的 Core 接口。选用某个 Kit 后，要遵守其局部输入输出约束。
新 App 必须提供什么
- 基础运行：Provider 的模型连接和实际输入。Core 提供默认预算、单次超时、信号与普通文本传输，按需要覆盖。
- 启用工具时：业务实现及所需身份、访问控制、参数与结果约束。
- 启用持久化时：来源、用户归属、存放与保留策略及失败恢复。
- 启用复杂编排时：声明节点、工具、模型能力、资料、检查与输出的关联。
不需要默认启用长期记忆、用户画像、经验库、向量数据库或动态工具加载。可以先交付一个只读、单轮、明确来源的 App，再按真实需求逐项接入。
已提供与需要自行实现的能力
| 库已提供 | App 仍需实现 |
|---|---|
| Knowledge 的文档解析、内存目录、章节选择和快照 | 读取文件／数据库、资料授权、版本计算、持久化导入／修改／删除 |
| Answering 的任务清单、检查和有界局部修正 | 任务业务定义、事实读取、模型调用、业务校验和允许的 fallback |
| Support 的上下文装配和模型调用格式适配 | 请求数据、服务端身份、来源可信度、存储和模型连接配置 |
| TextSkills 的文本目录加载和元数据校验 | 实际文件读取、工具引用核验、更新发布和重新加载时机 |
| Core 的运行记录和可选诊断、Support 的可选 Provider observer | 日志输出、存储、敏感内容策略、查询和运维 |
可复制运行的离线完整代码见服务问答示例。parse／define 在内存中解析和编译资料。资料准备与更新见资料维护 flow。
画像合并、经验学习、长期记忆存储、文档持久化、向量索引存储及文件摄取由 App 实现。相关章节提供接入边界与范本。