织点 AgentLoom 低代码 Agent 平台需求文档
需求版本 v0.2 · 实现状态更新于 2026-10-09 · 代码核对基线 9941e31 · 开发测试阶段
本平台面向团队，通过集中管理模型、Skill、工具和知识库，让开发者以配置方式创建 Agent，发布为网页应用和 API，并对已发布版本进行调试。本版记录已确认产品范围和后续目标。当前已有 Vue、FastAPI、SQLite / PostgreSQL 实现；验收标准仍包含尚待真实供应商和容器环境验证的项目。项目名称为织点，英文名 AgentLoom。
需求表达产品预期，验收项不表示均已完成。当前整体实现见技术设计，API/数据与部署分别见平台设计、部署运维。本次只整理现有需求和实现，业务 Wiki 的新形态暂缓。
当前需求落实概览
| 状态 | 范围 |
|---|---|
| 已实现，有隔离测试 | Vue/FastAPI、空间基础权限、PostgreSQL/SQLite、发布后运行、统一 Loop、自动 Plan、子模板、工具事件总线、连续会话、80%/轮数压缩、可信 Hooks、Embedding Hooks、系统文件工具与共享 POSIX 适配 |
| 已有代码，需真实环境验收 | DeepSeek/OpenAI 调用、Docker Skill/托管工具、NFS/NAS 跨节点锁和故障恢复；不能用替身测试代替 |
| 部分实现 | Skill 宿主能力兼容、发布资产/凭据生命周期、模型窗口自动元信息、细粒度来源追踪、知识索引版本与页面管理 |
| 尚未实现 | 集群调度/租约、MemoryService、隔离 Hook Worker/上传管理、实时输入队列、完整 RBAC、私有 Git、token 级响应流 |
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 | 自动生成执行计划并执行，不要求用户逐次批准计划。 |
| 会话上下文 | 一次提问的多次 Loop 共用执行上下文；同会话新提问使用新执行线程，并在处理前继承全部已提交且当前授权可见的历史交互。目标细则见第 7 节。 |
| 发布 | 发布后可直接在页面使用，也可通过 API 调用。 |
| 知识库 | 使用 RAG 检索增强生成。上传 Markdown、TXT、SQL 文本，Agent 按需检索并在回答中引用来源。SQL 作为资料，数据库执行是独立工具能力。 |
| 正式前端 | Vue 3 + TypeScript；开发页面与发布使用页面均由 Vue 实现。正式实现位于 apps/web；旧静态 Demo 保留用于历史交互评审。 |
| 部署 | Python 后端，最终部署到用户服务器。当前为开发测试阶段，单机优先。 |
已采用的产品约定
- Skills、工具、模型连接和知识库均归属空间，供空间中的多个 Agent 复用。
- Agent 使用草稿与不可变发布版本；发布快照固定资源版本，修改草稿不影响已发布应用。
- 仅空间管理者管理成员和密钥，空间成员可以开发与使用 Agent；更细权限后续扩展。
- 正式前端采用 Vue 3 + TypeScript，后端采用 FastAPI；支持 PostgreSQL 和隔离测试用 SQLite。工作区采用本地或共享 POSIX 存储，系统命令和托管工具依赖 Docker。
- 子 Agent 配置内嵌于主 Agent，并随主 Agent 一起发布。运行时按需创建，统一继承主 Agent 的模型与连接；当前每 Run 最多 8 次委派；具体实例、超时和调用预算见 Runtime 设计。
当前发布固定配置；知识索引可通过 API 重建为新资源并重新发布，尚非完整的版本浏览/回滚产品。更细权限与独立执行服务仍待建设。资源物理包、密钥轮换和文档删除的边界见平台设计。
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 只传给服务端保存，存储加密，日志脱敏。前端展示连接名或掩码，不读取原文。
- 连接测试区分凭据无效、模型不存在、请求超时和额度异常。
- 各模型的工具调用、流式输出和上下文能力要实际验证；不因协议相似假设功能完全一致。
- 用户配置引用模型连接；数据库发布快照包含资源的加密 secret 副本，公开接口不返回原文。运行聊天模型按资源 ID 刷新 Key，连接身份仍固定于快照。同连接轮换 Key 可生效；更换 provider/base URL 应创建新资源再发布，当前代码尚缺这类身份迁移的一致性保护。
- 填写 Key 后可发现可用模型；窗口信息优先使用可用元信息与已知目录，缺失时保守回退并允许调整。不能假设供应商
/models必然返回完整窗口、输出上限和能力数据。
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，也不需要重新训练聊天模型。
当前差距：已实现按行/大小分块，尚未实现语义化标题/完整 SQL DDL 分块。索引重建通过新知识库资源完成；检索结果含文档 ID、文件名、行范围、正文和分数，尚不含独立文档版本字段。上传保留 basename，不提供 Wiki 路径或 Agent 全文阅读工具。下列条目保留验收目标，API/页面的实际覆盖见平台设计。
文档上传与索引
- 首批支持 .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。模型返回候选结果后检查目标、工具证据与计划；仍有可执行工作则继续，确实缺少条件则等待补充。上下文按完整工具调用组压缩，保留目标、事实、计划与近期结果。检查点加密存储；失败、取消、等待补充或中断时允许原用户恢复同一发布版本。已完成调用不重放，结果未知的调用先检查实际状态。限制轮次、超时和子任务预算，提供停止入口。
会话连续性与执行线程（已确认目标）
逻辑执行线程由 (run_id, instance_id) 标识：每次新提问创建新 Run 和根实例，一次请求的多次 Loop 共用该实例上下文；同一会话内不同新提问使用不同执行线程。恢复及补充信息沿用原 Run、原实例，包括 resume 的补充输入，不等同于发起新提问。
新提问在首次模型调用前，必须继承同会话此前全部已提交且当前授权可见的历史交互，包括用户提问和回答、此前各 Loop 的模型消息、工具调用参数与结果、MCP 交互、Skill 加载内容及资源引用、知识和文件资料、错误与状态记录。失败、取消 Run 已发生的记录也属于历史，不能仅取最近 6 个成功 Run 或最终问答。历史可压缩，大内容可按引用读取，但来源必须完整可追溯，不能把继承历史缩为最终回答摘要。旧 pending 调用、取消标记、单次 Run 的执行预算计数及其他可变执行状态不能继续到新 Run；压缩触发计数及基线属于会话上下文元数据，按下节规则继承。
同会话新提问默认串行；有活动 Run 时沿用当前拒绝策略，本次不引入新提问队列。运行中补充队列仍为目标设计，补充归属原 Run。历史 Skill 加载不赋予新增工具权限，凭据不进入上下文；子实例内部上下文继续隔离，仅显式导出的结果、证据及引用进入父实例和会话历史。当前已实现连续主实例历史、补充记录和兼容视图继承；完整引用追踪、资源撤销后逐项过滤及工具大结果按需回读仍有差距。具体见Runtime 设计及上下文管理：会话、执行线程与历史继承。
可配置的主动上下文压缩（基础实现已落地）
压缩必须在达到配置阈值时主动触发，不能等请求超过模型窗口。平台提供默认策略，Agent 开发页通过高级配置覆盖；解析后的策略随 Agent 发布冻结，网页与 API 共用，原会话与恢复继续使用原发布策略。当前新配置使用预算与交接摘要策略，已提供比例及轮数配置页面；旧发布未配置策略时保留字符阈值兼容。Token 采用保守估算，精确供应商计数与完整来源块设计仍需完善。
| 配置项 | 当前默认值与约束 |
|---|---|
| 上下文占用比例 | 默认 0.80。分母为有效输入预算 InputBudget：模型窗口减去输出预留及安全余量，并受模型独立输入上限约束。完整请求的预计输入量达到该比例即触发。 |
新提问轮数 user_turns | 默认 null，不启用；可配置正整数。一个新提问 / 新 Run 计一次，同请求补充、恢复和重试不另计。 |
模型步骤数 model_steps | 默认 null，不启用；可配置正整数。只计有效且已持久化的 action 模型响应；压缩、完成检查调用及子实例响应不计入父实例。 |
| 压缩后目标占用比例 | 建议默认 0.60；启用占用比例触发时须低于触发比例，避免压缩后立即重复触发。 |
任一启用条件达到阈值（>=），即在下一次安全的模型调用边界执行压缩。轮次计数以最近一次成功压缩时的观测水位为基线，通过会话历史快照传给新 Run；新提问或恢复不能清零，失败压缩不能推进基线，重复投递不能重复计数。主、子实例计数独立。压缩只处理完整且已完成的交互组，保留当前任务、有效约束及未完成调用；没有可压缩组时记录延后原因，不反复空转压缩。
触发策略与模型硬上限分开：新发布的 BudgetCompactionPolicy 即使关闭比例触发、只启用轮次条件，仍校验完整请求的硬预算。旧字符策略及未实现可选 validate_request 的自定义策略不自动获得该校验；自定义模块须保持这项目标约束。无法满足预算时给出明确错误。详细配置、计数恢复与预算公式见上下文管理：Token 预算与主动压缩。
事件总线与工具解耦
Loop 将模型的工具调用转成统一 tool.execute 请求，提交到事件总线并等待关联结果，不按具体工具名称分支执行。工具定义与处理器独立注册；文件读写、Skill 内容、MCP、RAG、计划维护和子任务委派由各自处理器完成。新增工具无需修改 Loop。
每个请求包含调用 ID、工具名称、参数和恢复状态；总线分配关联 ID，成功或失败通过统一 ToolOutcome 返回。可信上下文由平台注入，权限和参数校验在工具运行时完成。取消与超时须传播到处理器并等待清理；外部操作不会自动重试。请求进度与处理器状态进入检查点，兼容已有子任务恢复。
执行请求与通知订阅分开：一个请求交给一个处理器，日志与指标等可以作为观察者订阅通知。首版使用进程内 asyncio 总线，PostgreSQL 保存事件与检查点；跨进程消息队列和分布式执行属于后续扩展。
子 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决定重试、调整任务或直接处理。当前不递归、顺序委派，最多配置 10 个模板，每 Run 最多执行 8 次委派；子实例初始上下文不自动复制父对话，由委派任务显式传递所需背景。并行调度仍待设计。
发布版本
草稿不允许运行或调试，调试只能使用已发布版本；修改配置后必须重新发布才能调试新配置。发布前校验模型连接、资源可用性、子 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、plan.updated、tool.completed、completion.review、run.blocked、run.resumed、run.completed 和 run.failed；当前回答在完成后返回，尚未实现模型 token 级输出。返回 run_id、session_id 与实际版本；API Key 绑定空间。当前请求契约见 OpenAPI，完整路由、响应和鉴权见平台 API 文档。部分响应仍是普通 dict，前端类型尚未全部从契约自动生成。
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 | run_id、instance_id、加密的主/子任务上下文、计划、工具进度、更新时刻；用于原 Run 恢复 |
| Session | session_id、space_id、访问授权、Agent 版本；组织各 Run 已提交历史及来源引用 |
| Run / AgentInstance | run_id、session_id、instance_id、父实例 ID、输入输出、运行状态、引用与产物；每个新提问创建新 Run/根实例，多次 Loop 和恢复沿用 |
| RunEvent / 上下文源记录 | run_id、instance_id、顺序、交互类型、内容或引用、资源版本、错误与状态；目标为新 Run 重建授权历史，来源须完整可追溯 |
| 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 不出现在浏览器存储、返回数据、产物或日志中；工作区不能读写其他空间文件。
- 会话连续性：一次提问的多次 Loop 保持相同
(run_id, instance_id)，新提问更换 Run 和根实例，恢复/补充保留原标识。跨越 6 个以上 Run 后，仍能按来源回查此前工具参数与结果、MCP、Skill、知识与文件以及失败/取消记录；压缩不丢失来源，不把旧 pending、取消或单次 Run 的执行预算计数作为新执行状态。活动 Run 期间的新提问继续被拒绝；权限撤回后不读取相关历史，历史 Skill 不扩大工具权限，子实例未导出的内部上下文和凭据不可见。 - 主动压缩：默认在有效输入预算的 80% 触发，而非等到超限；验证仅启用比例条件时低于阈值不触发、等于阈值触发，任一轮次阈值可独立触发，配置随发布固定。新提问继承兼容的计数基线，恢复旧 Run 后再次提问不漏算其他历史；恢复、重试和失败压缩不重置或重复计数，子实例及辅助模型调用不增加父实例步骤数。只压缩完整组并保留任务约束，无可压缩内容或软阈值持续命中时不反复请求摘要，所有请求仍遵守模型硬上限。
10 分阶段交付
| 阶段 | 交付内容 |
|---|---|
| 历史：需求与前端演示 | 评审页面、配置流程、模拟运行与发布；资源元数据可在本机浏览器保存。没有真实登录、上传、Git 拉取、MCP、模型调用或 API。 |
| 基础真实闭环 | Python API、模型连接、Agent 配置与版本、网页/API 运行、基础空间访问和事件记录。 |
| 完整资源执行 | Skill 导入与隔离执行、外部和托管 MCP、RAG 混合检索与引用、子 Agent、Plan。 |
| 稳定化 | 取消、超时、依赖校验、版本一致性、部署文档与集成验收。 |
11 待确认与非首期范围
已落地：资源空间共享、配置发布快照、基础 owner/member、公开 Git、默认无网络命令沙箱、上传/执行限额、可配置 Embedding 与 SQL JSON 向量。待扩展：私有 Git 凭据、受控联网策略、精细资源与成员权限、完整索引生命周期和版本界面。实现状态和已知限制见技术设计，不再将上述已采用约定重复列为待确认。
非首期：复杂角色体系、可视化图编排、计费、市场、分布式调度、高可用故障迁移、PDF/Word 解析。后续可按实际需求添加。
12 实现与验证状态
后端拆分业务路由和服务，前端拆分配置页、发布页与运行状态模块。数据库使用编号 SQL 迁移并兼容原有数据。任务状态与结束事件事务提交，SSE 支持续接与去重，页面有限次数自动重连并显示连接状态，历史恢复保留用户补充信息。
模型接口支持有限次数的连接/临时服务错误重试，并校验聊天与 embedding 响应；读取超时不自动重试。代码基线 9941e31 最近一次隔离回归记录为 540 项 Python、12 项前端测试及构建通过；本次文档更新未重新运行。早期浏览器 QA 使用独立数据与替身模型。真实供应商、Docker、共享卷和服务器部署需要分别实机验收；这些不能由替身测试替代。
PostgreSQL 数据库接入
支持通过项目 .env 配置 PostgreSQL，现有开发连接使用本机 127.0.0.1:15432 SSH 隧道。应用加载 DB_HOST、DB_PORT、DB_NAME、DB_USER 和 DB_PASSWORD，密码不进入代码或前端；连接失败不回退本地 SQLite。数据库迁移自动建表，发布版本、事件序号和知识库版本通过事务锁保护。
知识检索使用 PostgreSQL GIN 全文索引，保留中文和 SQL 标识符查询，向量仍以文本形式存储并在 Python 中计算相似度。任务结束时数据库断开，会保留待收尾状态并在恢复连接后幂等提交，不重放工具执行。接入 PostgreSQL 后仍为单进程运行，Skill 文件、解密密钥、旧 data/runs 和新 data/workspaces 或外置共享卷须与数据库成套备份。
2026-10-02 事件总线改造完成：Loop 统一请求，工具独立注册，24 项总线与工具运行时测试通过。当次本地完整回归与构建通过，PostgreSQL 复测因 SSH 隧道未监听而停在连接阶段。这是历史记录，不代表当前隧道状态；本次文档整理未连接远程数据库。
13 运行与演示说明
正式工作台由 Vue 与 Python 后端提供，使用 PostgreSQL 或 SQLite 服务端存储。首次创建管理员，添加真实模型连接，发布 Agent 后运行。任务历史和继续入口使用实际检查点；供应商端到端调用需要真实 Key。以下说明仅适用于 apps/web-demo 中保留的旧静态演示。
从 Agent 工作台进入。先配置研发知识助手，切换执行模式或绑定资源，保存草稿并发布，再发起测试任务；在发布页面测试聊天和查看 API 示例。资源管理支持模拟导入，只有元数据保存到当前浏览器。演示不接收真实密钥，不执行文件或 Git 操作。