gori-agent/.kimi-code/skills/gori-agent-deploy/SKILL.md

---
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/<bot-id>/`
- 实例配置：`<instance>/config.json`
- 实例 state：`<instance>/state/`
- Assistant Kimi home：`<instance>/state/kimi/assistant/`
- Worker Kimi home：`<instance>/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@<host> '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. **实例配置**
   - 先备份 `<instance>/config.json`。
   - Kimi ACP `bot.agent.args` 必须严格为 `["acp"]`。
   - Worker 如需独立 Kimi home，设置：
     ```json
     "bot": {
       "agent": {
         "env": { "KIMI_CODE_HOME": "<instance>/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 <bot-id>
   bin/gori-agent restart <bot-id>
   bin/gori-agent status <bot-id>
   ```
   - Health 必须是 HTTP 200 且 bot/platform identity verified。
   - restart 前检查是否有 `working` Proposal；working 时先告知用户，避免把 worker 打成 `worker_lost`。

## Assistant / Worker 模型配置

Assistant 和 Worker 可以有独立 `KIMI_CODE_HOME`：

```text
Assistant: <instance>/state/kimi/assistant/config.toml
Worker:    <instance>/state/kimi/worker/config.toml
```

流程：

1. 从本机基础配置复制：
   ```bash
   cp "$HOME/.kimi-code/config.toml" "<instance>/state/kimi/assistant/config.toml"
   cp "$HOME/.kimi-code/config.toml" "<instance>/state/kimi/worker/config.toml"
   ```
2. 如果使用 managed Kimi 模型，复制 OAuth/credentials：
   ```bash
   cp -a "$HOME/.kimi-code/oauth/." "<instance>/state/kimi/<role>/oauth/"
   cp -a "$HOME/.kimi-code/credentials/." "<instance>/state/kimi/<role>/credentials/"
   ```
   目录 `0700`，文件 `0600`，不回显内容。
3. 设置：
   ```toml
   default_model = "<model-alias>"
   [thinking]
   enabled = true
   effort = "<effort>"
   ```
4. 校验：
   ```bash
   "$HOME/.kimi-code/bin/kimi" doctor config "<instance>/state/kimi/<role>/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 <bot-id>
```

并确认：

- 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