From 33854721bf7aaa8edf6b46ae94a7263b1cc0412b Mon Sep 17 00:00:00 2001 From: zenord Date: Tue, 18 Aug 2026 22:57:23 +0800 Subject: [PATCH] docs: add gori-agent deployment skill --- .kimi-code/skills/gori-agent-deploy/SKILL.md | 191 +++++++++++++++++++ AGENTS.md | 2 + README.md | 2 + 3 files changed, 195 insertions(+) create mode 100644 .kimi-code/skills/gori-agent-deploy/SKILL.md diff --git a/.kimi-code/skills/gori-agent-deploy/SKILL.md b/.kimi-code/skills/gori-agent-deploy/SKILL.md new file mode 100644 index 0000000..93861d3 --- /dev/null +++ b/.kimi-code/skills/gori-agent-deploy/SKILL.md @@ -0,0 +1,191 @@ +--- +name: gori-agent-deploy +description: gori-agent Bot 的代码发布、实例配置、Assistant/Worker 模型与讲话人格配置流程 +whenToUse: 当用户要求部署、更新、重启、配置 gori-agent Bot（如 gori-ops、gori-developer），或要求配置 Assistant/Worker 模型、effort、persona/assistantPersona 时使用 +--- + +# gori-agent Bot 部署与配置流程 + +本 skill 用于把 `gori-agent` 代码发布到运行机，并配置实例的 Assistant/Worker Kimi Code 模型与讲话人格。核心边界：Assistant 只聊天和调度，Worker 只在已确认 Proposal 中执行；不要绕过 Proposal 状态机。 + +## 固定路径 + +- 仓库：`/home/ubuntu/gori-space/gori-agent` +- 实例根：`${GORI_AGENT_ROOT:-$HOME/.gori-agent}/instances//` +- 实例配置：`/config.json` +- 实例 state：`/state/` +- Assistant Kimi home：`/state/kimi/assistant/` +- Worker Kimi home：`/state/kimi/worker/` +- 本机 Kimi 基础配置：`$HOME/.kimi-code/config.toml` +- Kimi OAuth/credentials：`$HOME/.kimi-code/oauth/`、`$HOME/.kimi-code/credentials/` + +## 安全纪律 + +- 不在回复、日志、diff 中输出 platform secret、API key、OAuth 内容、消息正文、完整 chat/user ID。 +- `git commit/push/pull --rebase/reset/clean` 等 git mutation 必须得到用户当次明确授权。 +- 远程机器写入、部署、重启真实 Bot 必须得到用户当次明确授权。 +- 改实例 `config.json` 前必须同目录备份，写入用临时文件 + fsync + atomic rename，最终 `0600`。 +- 旧 state 不删除；需要切换版本时改成时间戳 `.bak` 保留。 + +## 发布流程 + +1. **确认源仓库状态** + - `git status --short --branch` + - 如果本地有未提交改动且用户要求远端部署，先提示：远端 pull 拿不到未提交代码。 + - 只有用户明确授权后才 commit/push。 + +2. **本地验收** + ```bash + npm run typecheck + npm test + npm run build + git diff --check + bash -n install.sh gori-agent.sh bin/gori-agent + ``` + +3. **目标机更新** + ```bash + ssh ubuntu@ 'cd /home/ubuntu/gori-space/gori-agent && git pull --ff-only origin master && npm run typecheck && npm test && npm run build' + ``` + - `git pull --ff-only` 失败、工作区脏或分叉时停止并报告，不擅自 reset/rebase。 + +4. **实例配置** + - 先备份 `/config.json`。 + - Kimi ACP `bot.agent.args` 必须严格为 `["acp"]`。 + - Worker 如需独立 Kimi home，设置： + ```json + "bot": { + "agent": { + "env": { "KIMI_CODE_HOME": "/state/kimi/worker" } + } + } + ``` + - `runtime.acp.promptTimeoutMs` 当前基线为 `14400000`（4 小时）。 + - `runtime.acp.maxAssistantSessions` 当前基线为 `4`。 + +5. **旧 state 处理** + - state v3 会拒绝旧 v1/v2。 + - 升级时如需 fresh start，把旧文件移动为： + ```text + acp-sessions.json.YYYYMMDD-HHMMSS.bak + ``` + - 不覆盖、不删除旧 state。 + +6. **doctor / restart / status** + ```bash + bin/gori-agent doctor + bin/gori-agent restart + bin/gori-agent status + ``` + - Health 必须是 HTTP 200 且 bot/platform identity verified。 + - restart 前检查是否有 `working` Proposal；working 时先告知用户，避免把 worker 打成 `worker_lost`。 + +## Assistant / Worker 模型配置 + +Assistant 和 Worker 可以有独立 `KIMI_CODE_HOME`： + +```text +Assistant: /state/kimi/assistant/config.toml +Worker: /state/kimi/worker/config.toml +``` + +流程： + +1. 从本机基础配置复制： + ```bash + cp "$HOME/.kimi-code/config.toml" "/state/kimi/assistant/config.toml" + cp "$HOME/.kimi-code/config.toml" "/state/kimi/worker/config.toml" + ``` +2. 如果使用 managed Kimi 模型，复制 OAuth/credentials： + ```bash + cp -a "$HOME/.kimi-code/oauth/." "/state/kimi//oauth/" + cp -a "$HOME/.kimi-code/credentials/." "/state/kimi//credentials/" + ``` + 目录 `0700`，文件 `0600`，不回显内容。 +3. 设置： + ```toml + default_model = "" + [thinking] + enabled = true + effort = "" + ``` +4. 校验： + ```bash + "$HOME/.kimi-code/bin/kimi" doctor config "/state/kimi//config.toml" + ``` + +当前生产基线（2026-08-18）： + +| Bot | Assistant | Worker | +|---|---|---| +| `gori-ops` | `kimi-code/k3-256k`, `high` | `kimi-code/k3-256k`, `high` | +| `gori-developer` | `kimi-code/k3-256k`, `high` | `kimi-code/k3`, `high` | + +注意：`k3-256k` 支持 `low/high/max`，不支持 `medium`；写 `medium` 会按模型默认回落。模型 availability 和 effort 通道异常时，先用只读/小请求验证，再调整。 + +## Assistant / Worker 人格配置 + +Config v3 支持： + +```json +{ + "bot": { + "persona": "Worker 的执行边界和安全规则。", + "assistantPersona": "Assistant 的讲话人格。" + } +} +``` + +- Worker 永远使用 `bot.persona`。 +- Assistant 使用 `bot.assistantPersona`；为空时回退 `bot.persona`。 +- `assistantPersona` 参与 Bot fingerprint；修改后旧 Assistant binding 会因 fingerprint 不匹配自动重建。 +- Assistant 的人话风格由 bootstrap 统一约束；实例 persona 决定角色气质。 + +当前实例人格： + +### gori-ops + +```text +你是 Gori 运维 Assistant。说话像一个靠谱、轻松的运维同事：先给结论，再给原因和下一步；用短句，少术语，不机械复读状态字段。遇到故障先稳住用户，再给可操作选择；不确定就直说。涉及部署、删除、Git mutation、远程写入或共享状态时，用平实的话说明影响并请用户确认；绝不回显 secrets。 +``` + +### gori-developer + +```text +你是 Gori 开发 Assistant。说话像一位资深开发搭档：直接、清楚、有判断力；先说结论，再给关键改动或验证方式；不堆内部字段和协议词，不机械复读 ID。能确定就明确说，不能确定就直说；遇到风险改动、Git mutation、部署或共享状态变化时，用平实的话说明影响并请用户确认；绝不回显 secrets。 +``` + +## QQ 发送边界 + +当前 QQ Bot 没有主动群消息权限，错误码： + +```text +40034105 主动消息失败, 无权限 +``` + +因此事件通知按方案 B： + +- 群聊 worker event 优先使用最近入站消息的 5 分钟被动回复窗口；实现按 4.5 分钟保守判定。 +- 私聊按 60 分钟窗口；实现按 55 分钟保守判定。 +- 超过窗口不主动发；事件进入 pending，下次该 chat 有入站时补发。 +- 无 `msg_id` 时不要发送裸 `msg_seq`。 +- 同一 `msg_id` 的 `msg_seq` 必须由 Gateway 共享递增，正常回复、事件、补发不能各自从 1 开始。 +- `/status` 应能看到 `schedulerState`、`blockedReason`、`lastEventDelivery`、`lastEventError`、`lastEventAt`。 + +## 验收清单 + +部署完成后至少检查： + +```bash +git status --short --branch +bin/gori-agent status +``` + +并确认： + +- runner PID 正常 +- Health HTTP 200 且 identity verified +- QQ websocket connected/ready（若使用 websocket） +- 没有 working Proposal 被误重启 +- Assistant/Worker Kimi config 均通过 `kimi doctor config` +- 日志中无新的 send failed、worker crash、assistant isolation violation diff --git a/AGENTS.md b/AGENTS.md index 62ac200..abaa1c3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -250,6 +250,8 @@ QQ WebSocket 仅在 qq + websocket 模式启动。`GET /health` 只输出 config ## 8. 测试与验收 +项目级部署/配置 skill 位于 `.kimi-code/skills/gori-agent-deploy/SKILL.md`；真实 Bot 部署、模型/persona 配置和 state 备份流程以该文件为准。 + 行为变化补测试，不削弱测试。配置 schema 变化同步： - `src/config.ts` diff --git a/README.md b/README.md index 4c6cbd1..69fffdd 100644 --- a/README.md +++ b/README.md @@ -264,6 +264,8 @@ Gateway 不维护普通消息队列或 per-chat task lock，也不再有固定 ## 开发验收 +项目级部署/配置 skill 位于 `.kimi-code/skills/gori-agent-deploy/SKILL.md`，覆盖代码发布、实例模型/人格配置、state 备份和 QQ 事件投递边界。 + ```bash npm run typecheck npm test