Skip to content

AI_Deployment_Guide.md

Latest commit

 

History

History
205 lines (147 loc) · 6.53 KB

AI_Deployment_Guide.md

File metadata and controls

205 lines (147 loc) · 6.53 KB

AI Deployment Guide

本文件是给 AI 代理执行部署任务的操作手册，目标是让代理在不猜测的前提下，稳定完成 飞书 x OpenCode 桥接服务 的部署与验收。

1. 事实基线（来自仓库）

  • Node.js 要求：>= 18（见 package.json）。
  • 桥接服务默认入口：dist/index.js。
  • 可用部署脚本（跨平台）：
    • scripts/deploy.mjs（菜单 + deploy/start/stop + Linux systemd）
    • scripts/start.mjs（后台启动）
    • scripts/stop.mjs（后台停止）
  • 脚本会自动检测 npm；若未检测到，会先询问是否显示安装引导，再由用户确认后处理。
  • 会话状态持久化：.chat-sessions.json。

2. 部署原则

  • 先验证环境，再执行部署。
  • 配置以 src/config.ts 实际读取字段为准。
  • 不把运行态文件（例如 .chat-sessions.json）作为部署产物提交。
  • 优先使用仓库内置脚本，不手写临时启动命令链。

3. 标准部署流程

步骤 A：环境检查

node -v
npm -v

要求 Node 主版本 >= 18。

步骤 B：准备配置

cp .env.example .env

至少填写：

  • FEISHU_APP_ID
  • FEISHU_APP_SECRET

建议同时确认：

  • OPENCODE_HOST（默认 localhost）
  • OPENCODE_PORT（默认 4096）
  • OPENCODE_SERVER_USERNAME（默认 opencode）
  • OPENCODE_SERVER_PASSWORD（OpenCode 启用密码时必填）
  • ENABLE_MANUAL_SESSION_BIND（默认 true，控制是否允许绑定已有会话）
  • TOOL_WHITELIST
  • PERMISSION_REQUEST_TIMEOUT_MS（默认 0，表示权限请求不超时，持续等待用户回复）
  • OUTPUT_UPDATE_INTERVAL
  • ATTACHMENT_MAX_SIZE

如果 OpenCode 进程启用了 OPENCODE_SERVER_PASSWORD，桥接进程必须使用同一组 OPENCODE_SERVER_USERNAME / OPENCODE_SERVER_PASSWORD。

ENABLE_MANUAL_SESSION_BIND 语义：

  • true：允许 /session <sessionId>；私聊建群卡片可选择“绑定已有会话”。
  • false：禁用手动绑定；私聊建群仅允许新建会话。

步骤 C：部署桥接

推荐命令（优先用平台脚本入口）：

bash scripts/deploy.sh deploy

Windows PowerShell：

.\scripts\deploy.ps1 deploy

这些入口会先自动检测 Node.js 与 npm：

  • Windows：若未检测到 Node.js，会询问是否自动安装（优先使用 winget，其次 choco），安装后自动重试。
  • Linux/macOS：若未检测到，会询问是否显示安装引导，再由用户确认后重试检测。
  • 若 .env 不存在，部署流程会自动从 .env.example 复制生成，且不会覆盖已有 .env。
  • 交互模式下，部署阶段可直接输入 FEISHU_APP_ID 与 FEISHU_APP_SECRET 写入 .env（支持回撤/跳过）。

步骤 D：启动 OpenCode

推荐使用菜单自动处理（安装/检查/启动）：

bash scripts/deploy.sh menu
.\scripts\deploy.ps1 menu

菜单项包含：

  • 安装/升级 OpenCode（npm i -g opencode-ai）
  • 检查 OpenCode 环境（安装状态 + 端口监听）
  • 启动 OpenCode CLI（自动写入 opencode.json 的 server 字段）

自动写入完成后，直接前台运行：

opencode

步骤 E：启动桥接服务

开发模式：

npm run dev

后台模式：

node scripts/start.mjs

停止后台：

node scripts/stop.mjs

更新升级（先拆卸清理再更新）：

bash scripts/deploy.sh upgrade

4. 平台速查

平台 菜单 一键部署 启动后台 停止后台 更新升级
Linux/macOS ./scripts/deploy.sh menu ./scripts/deploy.sh deploy ./scripts/start.sh ./scripts/stop.sh ./scripts/deploy.sh upgrade
Windows PowerShell .\\scripts\\deploy.ps1 menu .\\scripts\\deploy.ps1 deploy .\\scripts\\start.ps1 .\\scripts\\stop.ps1 .\\scripts\\deploy.ps1 upgrade

补充：菜单内已包含 OpenCode 安装/检查/启动与首次引导能力。

5. Linux systemd 常驻部署

前提：Linux + systemd + root 权限。

sudo node scripts/deploy.mjs service-install
sudo node scripts/deploy.mjs status

停用/卸载：

sudo node scripts/deploy.mjs service-disable
sudo node scripts/deploy.mjs service-uninstall

日志位置：

  • logs/service.log
  • logs/service.err

6. 飞书侧最小检查清单

  • 事件订阅：
    • im.message.receive_v1
    • card.action.trigger
    • im.message.recalled_v1
    • im.chat.member.user.deleted_v1
    • im.chat.disbanded_v1
  • 权限：
    • im:message
    • im:chat
    • im:resource

7. 验收步骤

  1. 在飞书群聊 @机器人发送普通文本。
  2. 观察是否收到流式回复。
  3. 触发一次权限请求，确认卡片按钮可用。
  4. 触发一次 question 提问，确认可以回复并继续对话。
  5. 执行 /undo，确认 OpenCode 和飞书消息都回滚。
  6. 在私聊执行 /create_chat，验证可看到并绑定 Web 端创建的跨工作区会话，点击“创建群聊”按选择生效。
  7. 执行 /clear free session，确认行为与“启动后自动扫描清理”一致。
  8. 执行 /compact，确认返回“上下文压缩完成”。
  9. 执行 !ls，确认 shell 命令可返回输出。
  10. 执行 /effort 与 /effort high，确认会话强度可查询/设置。
  11. 发送 #xhigh 请分析这段代码 后再执行 /effort，确认 # 仅临时覆盖，不改变会话默认强度。
  12. 执行 /clear_free_session <sessionId>，确认可删除指定 OpenCode 会话并移除本地绑定映射。

8. 常见异常与处理

  • 权限卡点击无效：检查回传是否为 once | always | reject。
  • 权限/提问卡未发送：检查 .chat-sessions.json 是否存在对应 sessionId -> chatId 映射。
  • 卡片更新失败：通常是消息类型不匹配，检查是否已自动降级为重发卡片。
  • OpenCode 接口返回 401/403：优先检查桥接端与 OpenCode 端的 OPENCODE_SERVER_USERNAME / OPENCODE_SERVER_PASSWORD 是否一致。
  • /compact 失败：优先检查当前可用模型，必要时先执行 /model <provider:model> 再重试。
  • ! 命令失败：确认命令在白名单内，并检查当前 Agent 是否可用（可先 /agent general）。
  • 后台进程残留：删除 logs/bridge.pid 前先确认目标进程是否仍在运行。

9. AI 代理执行要求

  • 不确定时先读源码再判断，不依赖历史印象。
  • 若用户要求提交代码，仅提交本次任务相关文件。
  • 推送前给出可复现的验证结果（至少包含构建/启动结果）。