织点 AgentLoom 低代码 Agent 平台需求文档
历史记录。 保留原阶段的能力、日期和测试数字，不作为当前实现清单。2026-10-09 核对后的现状见总体技术设计，当前需求见产品需求。
版本 v0.1 · 2026 年 9 月 30 日 · 开发测试阶段 · 待评审
本平台面向团队，通过集中管理模型、Skill、工具和知识库，让开发者以配置方式创建 Agent，发布为网页应用和 API，并对已发布版本进行调试。本版用于确认产品范围与交互，不代表后端已经实现。项目名称为织点，英文名 AgentLoom。
1 产品目标与范围
核心闭环：创建资源 → 配置 Agent → 发布版本 → 对话调试 → 网页或 API 使用 → 查看执行记录。优先实现实际运行能力；空间权限先采用基础成员访问，不引入复杂组织体系。
| 已确认需求 | 具体范围 |
|---|---|
| 多人和空间 | Agent 归属团队空间，成员有空间权限即可访问其中的 Agent。 |
| Skill | 采用 Codex / Claude Code 类 SKILL.md 技能包。支持文件夹上传、Git 地址导入，保留脚本、参考资料和附件；目标包含按需加载、命令执行、文件读写等实际能力。 |
| 工具 | 支持连接外部 MCP 服务和平台托管工具代码。提供 Python SDK 和开发示例，统一注册、测试和调用。 |
| 模型 | 首先支持 DeepSeek 和 OpenAI GPT 模型，具体模型 ID 可配置，不在需求阶段锁定版本。 |
| Agent 开发 | 配置模型、系统 Prompt、ReAct / Plan、Skills、工具、子 Agent、知识库。 |
| Plan | 自动生成执行计划并执行，不要求用户逐次批准计划。 |
| 发布 | 发布后可直接在页面使用，也可通过 API 调用。 |
| 知识库 | 使用 RAG 检索增强生成。上传 Markdown、TXT、SQL 文本，Agent 按需检索并在回答中引用来源。SQL 作为资料，数据库执行是独立工具能力。 |
| 正式前端 | Vue 3 + TypeScript；开发页面与发布使用页面均由 Vue 实现。正式实现位于 apps/web；旧静态 Demo 保留用于历史交互评审。 |
| 部署 | Python 后端，最终部署到用户服务器。当前为开发测试阶段，单机优先。 |
建议方案，需要评审
- Skills、工具、模型连接和知识库均归属空间，供空间中的多个 Agent 复用。
- Agent 使用草稿与不可变发布版本；发布快照固定资源版本，修改草稿不影响已发布应用。
- 仅空间管理者管理成员和密钥，空间成员可以开发与使用 Agent；更细权限后续扩展。
- 正式前端采用 Vue 3 + TypeScript；后端建议采用 FastAPI，开发阶段采用 SQLite 和本地文件存储；工具与脚本通过独立执行进程或容器运行。
- 子 Agent 配置内嵌于主 Agent，并随主 Agent 一起发布。运行时按需创建，统一继承主 Agent 的模型与连接；建议限制实例数量、超时和总运行预算。
Vue 前端和 Python 后端已确定；FastAPI、存储、执行隔离和版本策略为本版建议，仍需评审。
2 页面结构与主要流程
| 页面 | 操作与状态 |
|---|---|
| Agent 列表 | 查看团队 Agent、搜索、创建、进入配置或发布应用；区分草稿和已发布。 |
| Agent 配置 | 名称、模型、Prompt、策略、资源选择、子 Agent；保存草稿、发布；发布后调试。 |
| 调试面板 | 仅对已发布版本发送任务；显示输出、计划、执行状态、技能加载、工具调用、文件产物、引用与错误。展示可观察的行动过程，不承诺暴露模型内部思维链。 |
| Skills | 导入目录或 Git；查看 SKILL.md、目录、版本、依赖和校验结果。 |
| 工具 | 外部 MCP 地址及认证配置；或托管代码导入、构建和启动。发现工具 schema、测试输入输出、查看日志。 |
| 模型连接 | 供应商、Base URL、Key 引用、模型 ID、连接测试与状态；密钥不能明文回显。 |
| 知识库 | 创建库、上传文本文件、查看解析与索引状态、更新和移除文件、检索测试。 |
| 发布应用 | 运行发布版本、继续会话、查看文件产物与引用；查看 API 调用示例。 |
| 空间成员 | 基础成员管理和空间访问控制；本阶段低优先级。 |
首次使用流程：建立模型连接 → 导入 Skill / 工具 / 文档 → 新建 Agent → 选择模式与资源 → 发布 → 测试任务 → 通过网页或 API 完成同一类任务。
3 模型管理
- 供应商至少支持 DeepSeek、OpenAI。允许配置模型 ID 与接口地址，同一供应商可配置多个模型。
- Key 只传给服务端保存，存储加密，日志脱敏。前端展示连接名或掩码，不读取原文。
- 连接测试区分凭据无效、模型不存在、请求超时和额度异常。
- 各模型的工具调用、流式输出和上下文能力要实际验证；不因协议相似假设功能完全一致。
- Agent 关联模型连接，不直接复制密钥。发布版本固定模型 ID，允许凭据轮换。
4 Skill 管理与运行
兼容分为三层：目录与 SKILL.md 格式、技能发现和按需加载、运行时能力。导入成功不等于技能能完整执行。正式实现需对照 Codex / Claude Code 的官方规范建立兼容矩阵，并用真实技能包验证；此文档不声称已验证两者全部特性。
- 文件夹上传保留相对路径；根目录或选择的技能子目录应包含 SKILL.md。Git 支持指定分支/标签和子目录，记录实际 commit。
- 解析名称、描述与技能说明；校验失败给出文件路径和原因。需要容忍并保留未知元数据。
- 先提供描述用于发现，再按需加载详细指令与引用文件；每次运行只允许加载绑定的技能。
- 保留 scripts、references、assets 及其他附件。提供命令执行、文件读写、工作目录和产物下载。
- 声明和校验依赖；缺失依赖或宿主专属工具时提示“不兼容/待适配”，不能默默忽略。
- 运行工作区独立于平台源代码与密钥存储；限制路径、执行时间和资源，清理临时文件。
- 技能内容属于执行输入，不能绕过空间访问与运行时边界。支持更新为新版本，并保留历史版本。
目标是尽可能兼容已有技能包。Codex / Claude Code 专属工具、会话机制及依赖需要单独适配；完全兼容的具体范围待官方规范核对和样本验证。
5 工具平台与 MCP
外部服务
开发者部署 MCP 服务，平台作为客户端连接。配置服务地址、传输方式和认证，发现工具名称、描述和参数 schema，允许测试调用、刷新目录与查看错误。传输支持范围在实施时按官方 MCP 规范确定。
平台托管
开发者通过文件包或 Git 导入 Python 工具项目，提供依赖和启动入口。平台安装依赖、构建、启动服务、发现工具并管理版本、日志和失败状态。托管工具与外部工具对 Agent 暴露相同的工具目录。
开发者 SDK
提供函数声明方式，生成参数 schema、返回结果和错误映射，提供 MCP 服务启动入口。包含最小示例、本地调试说明和平台注册接口。SDK 底层应复用标准 MCP 实现；拟定注册 API 属于平台管理接口，与 MCP 协议分开。
第一版应有连接中、就绪、失败、构建中、停止状态，且错误可追溯到日志。删除仍被引用的工具时需要显示引用并阻止破坏发布版本。
6 知识库与 RAG
知识库采用 RAG（检索增强生成）：将上传资料建立检索索引，Agent 根据任务获取相关原文片段，再结合片段生成回答并引用来源。不会把全部文档固定加入系统 Prompt，也不需要重新训练聊天模型。
文档上传与索引
- 首批支持 .md、.markdown、.txt、.sql 文本文件，识别编码，保留文件名、来源、内容哈希和原文位置。
- 处理流程：上传 → 解析 → 分块 → 向量化与关键词索引 → 可检索；展示等待、解析中、索引中、就绪、失败，失败提供原因与重试。
- Markdown 按标题和段落组织分块；SQL 尽量保留完整表定义及相关注释，避免把表名、字段和解释拆散。分块参数由平台管理，第一版不要求每个 Agent 配置。
- 原文件、片段、关键词索引和向量索引分别保存并建立关联；更新或删除文件后同步生成新索引版本，不能返回已删除文件的旧片段。
检索与回答
- 采用关键词与向量混合检索：关键词匹配表名、字段、缩写等精确内容，向量检索匹配语义。召回数量与融合参数在检索测试后确定。
- 提供平台内置 knowledge_search 能力，输入查询与绑定知识库范围，返回相关片段、文件名、文档版本、位置和相关性信息；第一版不要求开发者部署额外 MCP 服务。
- 主 Agent 和子 Agent 都可绑定多个知识库，按任务需要调用检索；不因绑定了知识库就每轮强制检索。
- 知识库检索的空间和资源范围由服务端根据当前发布配置限制，不能依赖模型自行遵守空间 ID。
- 回答附带可打开的来源引用；没有相关证据时说明资料不足，不能生成不存在的引用。
- SQL 文件只用于理解表结构和示例，不自动执行；数据库查询与写入属于独立工具能力。
模型与配置
聊天模型与向量化模型独立管理。Agent 选择 DeepSeek 或 GPT；embedding 模型由平台统一配置，不要求主 Agent 或子 Agent 再单独选择。具体 embedding 供应商、模型与向量存储方案仍待验证，不假设现有聊天供应商支持 embedding。更换 embedding 模型需要重建向量索引，不能混用不同模型生成的向量。
页面与版本
知识库管理页包含文件上传、处理状态、索引版本、失败重试、文档更新/删除和检索测试。检索测试展示命中的原文片段与来源。Agent 配置页只选择知识库；发布前检查绑定库已可检索。建议发布快照固定知识库索引版本，文档更新生成新版本，重新发布 Agent 后生效。移除文件时历史索引保留与永久删除策略需要单独明确。
第一版交付“上传 → 建索引 → 混合检索 → 回答带引用”的闭环。重排序、知识图谱和更复杂的检索优化不属于首期必要能力。
7 Agent 运行与发布
ReAct 与 Plan
ReAct 逐步选择行动并处理观察结果。Plan 先生成结构化计划，再自动执行各步骤，支持根据失败或新信息调整计划。两种模式共用一个任务执行循环：模型决策 → 工具执行 → 结果反馈 → 再次决策。Plan 由模型通过 update_plan 持续维护，而非运行时固定按序执行。子 Agent 使用相同基础循环，但不配置独立模式。
运行状态：queued → running → succeeded / failed / cancelled / needs_input；重启中断记为 interrupted。计划步骤为 pending / in_progress / completed / cancelled。模型返回候选结果后检查目标、工具证据与计划；仍有可执行工作则继续，确实缺少条件则等待补充。上下文按完整工具调用组压缩，保留目标、事实、计划与近期结果。检查点加密存储；失败、取消、等待补充或中断时允许原用户恢复同一发布版本。已完成调用不重放，结果未知的调用先检查实际状态。限制轮次、超时和子任务预算，提供停止入口。
子 Agent 配置与动态创建
子 Agent 是主 Agent 内部的任务执行配置，不是选择空间里另一个独立发布的 Agent。配置项包括名称、职责与适用任务、系统 Prompt、Skills、工具及知识库。子 Agent 不单独配置 ReAct / Plan，负责执行主 Agent 委派的具体任务；执行模式仅在主 Agent 配置。子 Agent 不提供模型选择或独立 Key；运行时统一继承主 Agent 发布版本的模型连接。
主 Agent 根据任务复杂度与职责匹配决定是否创建一个或多个子 Agent，传入子任务和必要上下文。子 Agent 在自己的资源配置范围内管理工具调用、处理结果并向主 Agent 汇报；主 Agent 汇总最终回答。配置存在不意味着每次都必须启动子 Agent。子 Agent 实例随任务创建和结束，配置随主 Agent 快照发布，不独立发布或出现在团队 Agent 列表中。
记录实例 ID、父运行 ID、委派任务、继承模型、执行步骤、工具调用、输出与错误。失败时由主 Agent决定重试、调整任务或直接处理。递归创建、并行限额及上下文传递细节属于后续运行引擎设计。
发布版本
草稿不允许运行或调试，调试只能使用已发布版本；修改配置后必须重新发布才能调试新配置。发布前校验模型连接、资源可用性、子 Agent 配置和循环依赖。快照包含 Prompt、模式、模型 ID、资源版本。网页和 API 使用同一运行引擎。新发布不改变已开始的会话；会话固定其版本。回退通过选择旧发布版本实现。
API 建议契约
POST /api/v1/agents/{agent_id}/runs
Authorization: Bearer <space-scoped-api-key>
{
"input": "整理系统架构",
"version": 1,
"session_id": null,
"stream": true
}
GET /api/v1/runs/{run_id}
POST /api/v1/runs/{run_id}/cancel
GET /api/v1/agents/{agent_id}/runs
POST /api/v1/runs/{run_id}/resume {"input":"可选补充信息","stream":true}流式输出拟采用 SSE，事件包含 run.started、plan.created、step.started、tool.completed、output.delta、run.completed 和 run.failed。返回 run_id、session_id 与实际版本；API Key 绑定空间。具体字段在 contracts 中固定并共享给前后端。
8 数据模型建议
| 实体 | 核心字段 |
|---|---|
| Space / Member | 空间 ID、名称；用户、空间、基础身份 |
| ModelConnection | space_id、provider、base_url、model_id、secret_ref、状态 |
| Skill / SkillVersion | space_id、name、description、来源、commit、目录路径、版本、兼容性结果 |
| ToolService / ToolVersion | space_id、类型、endpoint、secret_ref、构建配置、schema、状态、版本 |
| KnowledgeBase / Document | space_id、名称、文件路径、内容哈希、文档版本、解析与索引状态 |
| Chunk / IndexVersion | 文档版本、片段正文、原文位置、embedding 模型、向量索引引用、关键词索引引用、索引版本与状态 |
| Agent / AgentVersion | space_id、草稿配置、模型引用、资源绑定、子 Agent 配置、发布快照 |
| Checkpoint | 运行 ID、加密的主/子任务上下文、计划、工具进度、更新时刻 |
| Session / Run / RunEvent | space_id、Agent 版本、输入输出、运行状态、结构化事件、引用、产物 |
| ApiCredential | space_id、密钥哈希、名称、有效期、撤销状态 |
9 第一版验收标准
- 空间成员可进入空间，非成员不能通过页面或 API 访问其 Agent 和资源。
- 分别配置 DeepSeek 和 OpenAI 模型，真实完成一次响应与一次工具调用；错误连接给出清晰原因。
- 分别通过文件夹和 Git 导入 Skill；加载引用资料，执行示例脚本并生成可下载产物；记录兼容性限制。
- 连接一个外部 MCP 服务，发现并成功调用工具；托管一个 Python 示例工具，完成构建、运行和调用。
- 上传 MD、TXT、SQL 后能查看处理状态并完成索引；关键词匹配正确的表/字段，语义查询返回相关片段；主 Agent 与子 Agent 能按授权范围检索，回答引用可定位原文件。无结果、失败重试、文档更新/删除与索引版本切换有明确行为。
- 同一 Agent 分别使用 ReAct 和 Plan 完成测试；Plan 自动产生并执行计划，失败或新信息出现后可以调整；提前交付被检查要求继续；上下文压缩不拆散工具调用；恢复不重放已完成动作，未知结果先观察。
- 主 Agent 能根据复杂任务按需创建子 Agent；子 Agent 使用继承的模型，并按自身 Prompt 及资源配置处理委派的子任务、管理工具调用和返回结果。简单任务不要求创建子 Agent。
- 发布后网页与 API 使用同一快照，编辑草稿不会影响已发布版本。
- 能查看运行事件、工具错误和超时，能终止正在执行的任务。
- Key 不出现在浏览器存储、返回数据、产物或日志中；工作区不能读写其他空间文件。
10 分阶段交付
| 阶段 | 交付内容 |
|---|---|
| 历史：需求与前端演示 | 评审页面、配置流程、模拟运行与发布；资源元数据可在本机浏览器保存。没有真实登录、上传、Git 拉取、MCP、模型调用或 API。 |
| 基础真实闭环 | Python API、模型连接、Agent 配置与版本、网页/API 运行、基础空间访问和事件记录。 |
| 完整资源执行 | Skill 导入与隔离执行、外部和托管 MCP、RAG 混合检索与引用、子 Agent、Plan。 |
| 稳定化 | 取消、超时、依赖校验、版本一致性、部署文档与集成验收。 |
11 待确认与非首期范围
待确认：资源是否全部空间共享；发布快照策略；Git 私有仓库认证；执行脚本的联网策略；上传和运行限额；embedding 供应商与向量存储；历史知识索引保留与删除策略；成员对开发配置的操作范围。实现状态和已知限制见 README 与实现验证记录。
非首期：复杂角色体系、可视化图编排、计费、市场、分布式调度、高可用故障迁移、PDF/Word 解析。后续可按实际需求添加。
12 运行与演示说明
正式工作台由 Vue 与 Python 后端提供，使用 SQLite 服务端存储。首次创建管理员，添加真实模型连接，发布 Agent 后运行。任务历史和继续入口使用实际检查点；供应商端到端调用需要真实 Key。以下说明仅适用于 apps/web-demo 中保留的旧静态演示。
从 Agent 工作台进入。先配置研发知识助手，切换执行模式或绑定资源，保存草稿并发布，再发起测试任务；在发布页面测试聊天和查看 API 示例。资源管理支持模拟导入，只有元数据保存到当前浏览器。演示不接收真实密钥，不执行文件或 Git 操作。