开发者手册

面向使用 Ai Lubricant 完成开发工作的用户：从登录、项目与任务开始，到 Agent、编辑器、终端和文件。

本页目录首次使用项目任务模型聊天Agent编辑器终端与文件资源/MCP安全

1. 首次使用

适用角色：平台普通用户、项目开发者。

前置条件：已有可登录的平台账号，并且已经拿到可用的 API Key、模型和（如需远程执行的）节点——自己部署时由你在管理端配置，多人使用时由管理员分配。

  1. 访问 /login，输入平台账号与密码。
  2. 登录成功后进入 /console/tasks；确认页面右上角显示正确用户和团队。
  3. 进入“我的”或相关设置，检查 Git identity；Agent 提交代码前应使用明确身份。
  4. 在“聊天”中选择被授权的 API Key 和模型，发送一条无敏感数据的测试消息。
  5. 在“项目”中选择已有项目，或按管理员授权创建新项目。
不要在提示词中粘贴凭据API Key、Cookie、SSH 私钥、数据库密码、TOTP secret 与客户数据应使用平台提供的专用凭据/资源配置，而不是写入聊天、任务描述或项目文件。

2. 项目：持续工作上下文

项目是任务、编辑器、仓库、提示词与成员协作的统一容器。Agent 工作前先选择项目，避免每次从空白上下文开始。

操作路径

  1. 从用户侧项目入口进入项目列表，选择项目。
  2. 在项目详情确认仓库/工作目录、任务、编辑器与项目提示词。
  3. 如果需要 Git 操作，确认自己的 Git identity 已配置且属于当前用户。
  4. 进入“编辑器”Tab 创建或打开项目编辑器；旧 /console/editors 路径已下线，编辑器必须归属项目。

预期结果

项目详情能看到任务与编辑器；后续任务、聊天或 Agent 会话能够引用项目上下文。

3. 任务：让 Agent 持续推进目标

创建任务

  1. 进入 /console/tasks，点击“新建任务”。
  2. 选择项目；填写清晰目标、验收标准和已知约束。
  3. 选择被授权的模型/API Key；如需自有机器执行，选择在线且获授权的 execution 节点。
  4. 仅显式选择任务需要的资源、技能与工具，遵循最小权限。
  5. 提交后进入任务详情，观察状态和 Agent 事件。

写好任务描述

应包含示例
目标“为订单 API 增加幂等键校验”
范围“只改后端订单模块与相应测试，不改前端”
验收“重复请求返回同一订单；新增单元测试；现有测试通过”
约束“复用现有 Redis client；不得记录完整请求体”

避免只写“优化一下”“修好它”等无法验证的目标；不要在任务描述中写密码、Token 或真实客户数据。

查看执行

  • 任务详情显示 Agent 消息、工具调用、终端输出、执行事件与最终结果。
  • 节点断开或 Provider 不可用时，任务会显示明确失败/等待状态；不要重复提交多个相同任务。
  • 完成后先审查代码 diff、终端输出和测试结果，再决定合并或发布。

4. 模型聊天：统一使用被授权模型

  1. 进入 /console/chat。
  2. 选择属于自己或团队授权的 API Key，以及该 Key 允许的模型。
  3. 输入消息；文件/媒体能力取决于模型 input_modalities 与渠道支持。
  4. 流式响应由后端统一网关提供；前端不会直接持有上游 Provider Token。
聊天也走生产主链路前端只提交 api_key_id，后端按当前用户权限解析真实 Key；路由、限流、日志和用量与 API 调用使用同一口径。

5. Agent：组合模型、提示词与工具

使用已有 Agent

  1. 进入 /console/agent-chat。
  2. 选择管理员提供的平台 Agent，或自己创建的 Agent。
  3. 确认 Agent 绑定的主模型、Sub-agent 模型与资源符合任务需要。
  4. 发起对话；Agent 的 MCP/工具调用会以当前运行用户身份校验权限。

创建/编辑 Agent

  • 主模型：必须选择自己有权限的网关 API Key 和模型。
  • Sub-agent：可绑定独立 Key/模型；只配模型时可复用主 Key。
  • 系统提示词：描述角色、目标、约束和交付格式，避免写入真实凭据。
  • 技能/插件/MCP：只选择需要的资源；平台提供的资源不会自动全部注入。
  • 工作区：限制 allowed roots 和 denied patterns，避免 Agent 访问无关目录。

6. 项目编辑器与会话

  1. 从项目详情的“编辑器”Tab 创建编辑器；选择工作节点与必要的环境配置。
  2. 进入 /console/editor/:editorId 查看编辑器详情。
  3. 新建/恢复编辑器会话；会话可关联终端与工作区。
  4. 完成工作后停止不再使用的会话，释放节点容量。

编辑器与项目一对一关联；历史 /console/project/:projectId/editor/:editorId 链接会重定向到新的顶层编辑器路由。

7. 终端与文件：无需自行准备 SSH/SFTP

终端

  1. 进入 /console/terminal 或项目/编辑器内终端入口。
  2. 选择获授权且在线的节点或会话。
  3. 平台通过浏览器 WebSocket 和 NodeConnect 帧桥接到节点 PTY；输入、输出和窗口缩放实时传递。
  4. 关闭页面或显式关闭终端后，平台通知节点释放 PTY；连接中断时节点会关闭残留终端。

文件

  1. 进入 /console/files，选择环境/节点与路径。
  2. 浏览目录、读取/编辑文件，或执行获授权的上传、创建、移动操作。
  3. 路径与文件内容遵循后端权限和工作区边界；不要访问项目之外的敏感目录。
“无需 SSH”的准确含义日常平台链路不需要用户开放 22 端口、准备 SSH Key 或自行安装 SFTP 工具；节点管理员仍需预先安装节点程序，并正确配置操作系统权限与出站网络。

8. 内置资源与 MCP

  • /console/resources：创建/查看自己的 CDP 浏览器 client、Mail 实例和对外 MCP token。
  • /console/mcp：配置用户级外部 SSE MCP；服务与工具按用户 scope 隔离。
  • CDP 浏览器扩展的 connection token 与外部 MCP access token 是不同凭据；前者连接扩展，后者调用 MCP，并且必须绑定具体 client。
  • Mail 工具只读查询被授权实例，无法跨实例读取其他用户邮箱。
  • 把资源加入 Agent 前先测试工具清单与作用域；任务结束后撤销临时 token。

9. 开发者安全与验收清单

  • 不给 Agent 无关的模型、工具、目录与节点权限。
  • 不在提示词、任务、聊天、代码或截图中放 API Key、Cookie、密码、私钥与客户数据。
  • 浏览器自动化使用隔离 Chrome profile；不要连接个人日常 profile。
  • Agent 修改代码后审查 diff、测试输出与依赖变更；不要只信最终总结。
  • 高风险命令、删除、发布与外部发送应由人工确认。
  • 任务完成后停止闲置会话、撤销临时 token 并检查异常节点/请求日志。