# gori-agent 项目施工指南

本文件供 Coding Agent 在本仓库施工时使用。先理解 Config v3 和实例隔离契约，再做最小、可验证的修改。

## 1. 项目定位与固定边界

`gori-agent` 是 Node.js 20+ / TypeScript 项目，通过单个 IM 平台接收请求，并通过官方 Agent Client Protocol（ACP）驱动一个 Coding Agent。

```text
用户 → Platform Adapter → Gateway → AssistantManager（Assistant / Proposal / Worker）→ ACP Agent
```

每个运行实例是一个完整且固定的 Bot：

- 一个 Gateway 进程。
- 一份 Config v3 本地配置。
- 一个 `bot.id`、workspace、persona。
- 一个 ACP agent。
- 一组直接声明的 skills 与一个 permission policy。
- 一个平台身份。
- 独立 PID、日志和 ACP state。

不要重新引入 Config v1/v2 migration、`roles[]`、动态 role selection、`backends[]`、多平台同时启用或单轮 CLI fallback。

## 2. 实例目录契约

统一实例根：

```text
${GORI_AGENT_ROOT:-$HOME/.gori-agent}/instances/<bot-id>/
├── config.json
├── logs/gori-agent.log
└── state/
    ├── acp-sessions.json
    ├── proposals.json
    ├── assistant-workspaces/
    ├── kimi/assistant/
    └── gori-agent.pid
```

实例目录本身就是该进程的 `GORI_AGENT_HOME`。约束：

- `bot.id` 只允许小写字母、数字和连字符，拒绝 `/`、`..` 等路径穿越。
- CLI 加载后必须校验目录名与 `config.bot.id` 相同。
- 实例目录、`logs/`、`state/` 为 `0700`。
- `config.json`、PID、state 为 `0600`。
- 多实例必须使用不同 `gateway.server.port` 和平台 credentials。
- 旧的 `/usr/bin/flock` workspace lease 与 `owner.json` 已退役，不要重新引入。同一 `GORI_AGENT_ROOT` 下由 workspace scope 兜底：`doctor`、外层 `start` 与内部 runner 扫描其他实例目录的完整 Config v3，任一目录/配置不可读或无效即 fail closed；canonical workspace 相同或互为父子一律拒绝。该机制不覆盖终端、IDE、其他 root 或未接入 gori-agent 的进程。
- `init` / `setup` 必须交互询问并校验 server host/port；扫描其他 Config v3 的声明端口，冲突时警告，新实例建议下一个未声明端口，已有配置不得静默改端口。
- `setup <bot-id>` 只重配已有实例：校验目录/config/PID，运行中或 foreign PID 拒绝，固定 Bot ID，保留 agent/skills/permissions/policy/runtime/secrets/publicBaseUrl，确认写入后运行 doctor。
- setup 的声明冲突提示不替代实际 bind 检查；`start` 对缺配置、ID 不匹配、错误权限、占位符、运行 PID、端口冲突 fail closed。
- start 只 spawn 构建后的内部 `dist/cli/instance-runner.js <config-path>`；PID identity 必须精确匹配 Node executable、runner 和唯一 config 参数。

公开入口仅有：

```bash
gori-agent init <bot-id>
gori-agent setup <bot-id>
gori-agent start <bot-id>
gori-agent stop <bot-id>
gori-agent restart <bot-id>
gori-agent status <bot-id>
gori-agent logs <bot-id>
gori-agent doctor <bot-id>
gori-agent list
```

不兼容旧 `instance` 前缀；不公开 debug 命令、`--config` 或 `--json`。

## 3. 核心代码结构

- `src/config.ts`
  - Config v3 Zod schema、类型、交叉校验和 state 默认路径。
  - 只接受 `configVersion: 3`。
- `src/server.ts`
  - 组装 fixed Bot、state store、ProposalStore、AssistantManager、Gateway 和唯一 platform adapter。
  - 只挂载所选平台 route；创建 AssistantManager 时传入 `runtime.acp.maxAssistantSessions`。
- `src/roles/role-registry.ts`
  - 历史路径名保留，但实现是 `BotProfileResolver`，不是 role registry。
  - 加载当前 Bot skills、计算 fingerprint、生成版本化 assistant/worker bootstrap。
  - Assistant 用 `bot.assistantPersona || bot.persona` 并带人话风格规则；Worker 始终用 `bot.persona`，bootstrap 保持严格。
- `src/acp/client.ts`
  - ACP initialize/new/resume/load/prompt/cancel 和 permission request。
  - assistant session 一旦出现 tool update 或 permission request 必须 fail closed。
- `src/acp/worker.ts`
  - worker 在 `bot.workspace` 启动；assistant 在实例私有 `state/assistant-workspaces/<hmac>` 启动，未显式配置时 `KIMI_CODE_HOME` 指向实例私有 `state/kimi/assistant/`。
  - 每个 ACP worker 使用独立进程组和随机 `GORI_AGENT_WORKER_TOKEN`；cancel、timeout、crash 或 assistant 隔离违约必须清理同进程组工具后代；bootstrap 禁止 `setsid`、`nohup`、detached/daemon/background 遗留进程，主动脱组属于无 cgroup/Bubblewrap 方案的边界。
  - assistant 只接受 Kimi Code ACP，并依赖项目级 `tools: []`、`subagents: []` profile；permission deny 只是附加层。
- `src/acp/assistant-manager.ts`
  - 每 conversation（chat + user）一个无工具 Assistant 会话，同群不同用户互相隔离（`GORI_ASSISTANT_ACTION_V2` envelope：create_proposal/confirm/adjust_proposal/follow_up/finish/send_image/start_next/cancel/stop，格式只修复一次）；runtime 执行 action 后在 reply 末尾追加人话纠正（如 start_next 被阻塞、无 owner 匹配），Assistant 不得自行宣称 action 已生效。
  - 唯一活跃 Worker 执行已确认 Proposal（`GORI_WORKER_RESULT_V2`：仅 `PENDING`，summary 必填，可带 question/workspaceDirty/attachments）；pending 不区分 success/fail，只有 finish 落定为 finished(done)，cancel 落定为 finished(cancelled)，不自动开始下一个。
  - envelope 解析先严格匹配（闭合标签 + 文本末尾 anchor）；缺闭合标签时从起始标签后做花括号配平（字符串/转义感知）salvage，配平点必须在文本末尾才接受，否则仍判无效走修复。worker 启动（new/resume session）、envelope 无效、repair 成败、settle（attachments/dropped 数）、worker_error、follow_up resume/fresh 兜底均有单行安全日志（proposal id 前 8 位，不含正文）。
  - capacity（maxAssistantSessions/maxProcesses）、idle sweep、cancel/confirm/finish/stop、worker_lost 恢复、owner 事件通知。
- `src/core/durable-session-store.ts`
  - state v3 只保存 bot/platform identity 和 assistant binding（conversation key，即 chat + user、agent ID、native session ID、assistant workspace、fingerprint、时间戳、`lastActiveAt`）；不保存消息正文。
  - 单 writer lock、串行持久化、临时文件、fsync、原子 rename；version/identity 不匹配（含旧 v1/v2）拒绝并保留原文件。
- `src/core/proposal-store.ts`
  - proposals.json（version 2）保存 Proposal：title/goal/steps、owner chat、发起用户 requesterUserId、状态流（proposed/queued/working/pending/finished）、pending（summary/question?/workspaceDirty?/receivedAt）、finished（finishKind done|cancelled、finishNote?）、worker session 与进程组 PGID/token；同样的 lock 与原子写入纪律。打开 v1 文件时先写 `proposals.json.v1-<timestamp>.bak`（0600）备份再按固定映射迁移。
- `src/core/workspace-scope.ts`
  - canonical workspace + 跨实例 Config v3 扫描；相同或父子 workspace 在 doctor/start/runner fail closed。lease 已退役。
- `src/core/workspace-images.ts`
  - 出站图片校验与读取：路径必须 resolved 在 canonical workspace 内、png/jpg magic bytes、单张 ≤10MB；发送时按路径重读。
- `src/core/gateway.ts`
  - 入站 allowlist、群 mention、命令和回复；不维护普通消息队列或 per-chat task lock，也没有固定时间处理中提醒。
  - 每条异步入站使用独立串行 ReplyStream，`replySequence` 从 1 动态递增；发送失败只写安全日志且不阻止任务或后续发送。
  - Worker 落定事件经 `sendEvent` 发送：优先引用该 chat 最近入站消息走被动回复窗口（群 4.5 分钟、C2C 55 分钟保守判定，`msg_id` + 递增 `msg_seq`）；`msg_seq` 按 chat+messageId 共享计数（正常回复、事件、补发同一计数器，QQ 重复推送同一 msg_id 时沿用已用序号）；无新鲜窗口或发送失败时不发主动消息，记录 lastEventDelivery/lastEventError/lastEventAt，补发失败保留队列并在下次入站时重试。
- `src/core/command-router.ts`
  - `/help`、`/status`、`/list`、`/confirm`、`/finish`、`/stop`、`/cancel`；未识别命令按普通消息处理。
- `src/platforms/*`
  - Adapter 依赖独立平台 config type，不依赖完整 AppConfig 路径。
- `src/cli/config-file.ts`
  - fail-closed 加载、example seed 与原子 `0600` 配置写入。
- `src/cli/instance.ts`
  - 实例目录、PID/log、端口和 lifecycle 管理。
- `src/cli/instance-runner.ts`
  - 非公开进程入口；加载单实例配置、启动 server，并处理 SIGINT/SIGTERM 优雅关闭。
- `src/cli/doctor.ts`
  - v3、Bot、agent、platform、state、permission 和 placeholder 检查。
- `src/agents/*`、`src/core/session-store.ts`
  - legacy compatibility/reference，不是当前运行链路。
- `dist/`
  - 构建产物；不手改，修改 TypeScript 后运行 `npm run build`。

## 4. Config v3 契约

仓库中唯一可提交配置说明是 `config.example.json`。它含明显占位符，可通过 schema，但不能启动实际 Bot。

顶层：

```text
configVersion  固定 3
bot            固定 Bot、agent、skills、permissions
gateway        server、入站 policy、唯一 platform
runtime.acp    state 和 ACP 生命周期
```

### 4.1 `bot`

```json
{
  "id": "bot-id",
  "workspace": "/absolute/path",
  "persona": "明确职责、边界和确认点。",
  "assistantPersona": "可选；Assistant 讲话人格，为空时回退 persona。Worker 始终用 persona。",
  "agent": {
    "id": "kimi",
    "command": "/absolute/path/to/kimi",
    "args": ["acp"],
    "env": {}
  },
  "skills": [],
  "permissions": {
    "mode": "deny",
    "allowedTools": [],
    "allowedCommandPatterns": []
  }
}
```

- workspace 必须绝对。
- 一个 Bot 只有一个 agent；不要添加 registry/reference。
- Kimi Code 应使用 `args: ["acp"]`。
- agent `shell: false`，cwd 为 workspace。
- 模型/provider 属于 ACP agent 自己的配置，不写入 gori-agent config。
- `env` 不得在模板、日志、diff 中泄漏 token。

### 4.2 Skills

`bot.skills[]` 每项直接声明：

```json
{ "id": "skill-id", "file": "/absolute/SKILL.md", "maxBytes": 256000 }
```

ID 唯一；文件须存在、可读、普通文件且未超限。skill 内容发送给 ACP，也进入 fingerprint；不得放 secret。

### 4.3 Permissions

- `deny`：默认，拒绝全部 permission request。
- `allowlist`：`toolCall.name` 与 `allowedTools` 精确匹配；bash/terminal 的 raw command 还要被 `allowedCommandPatterns` 完整覆盖。
- `auto`：高风险/yolo，只有用户明确授权才能设置。

permission policy 只审批 ACP request，不会注册工具。persona 不是安全边界。请求信息不足时拒绝。命令 regex 应锚定并限制参数，不使用任意 `.*` 全放行。

### 4.4 Gateway

- `gateway.server`: host、port、publicBaseUrl。
- `gateway.policy`: allowedUsers、allowedChats、requireMentionInGroup。
- `gateway.platform`: `type` discriminated union，只能是 qq、feishu、wecom、webhook、weixin 之一。
- 对象存在即启用，无 `enabled` 字段。

QQ 群 chat ID 为 `group:<group_openid>`；用户 ID 按 QQ 官方语义取值：群聊作者用 `member_openid`，C2C 私聊作者用 `user_openid`。正式运维 Bot 应配置入口 allowlist。

### 4.5 Runtime ACP

- `stateFile` 为空时为 `$GORI_AGENT_HOME/state/acp-sessions.json`；proposals 固定在同目录 `proposals.json`。
- `initializeTimeoutMs`: 默认 10000。
- `promptTimeoutMs`: 默认 14400000（4 小时）。
- `cancelGraceMs`: 默认 5000。
- `idleTimeoutMs`: 默认 1800000。
- `assistantSessionResetIdleMs`: 默认 3600000；`0` 禁用。Assistant 会话（按 binding 的 `lastActiveAt`，每轮刷新并持久化）空闲超过该阈值且该 owner（chat + user）没有任何 `proposed/queued/working/pending` Proposal 时，下一条消息删除 binding 开新 session（新 HMAC workspace 目录），而不是 resume 旧 session；有未完成 Proposal 则照常 resume。重置只在下一条入站消息时 lazy 发生，sweeper 不主动删 binding。
- `sweepIntervalMs`: 默认 60000。
- `maxProcesses`: 默认 8，包含 assistant + worker。
- `maxAssistantSessions`: 默认 4。

Kimi Code agent `args` 必须严格为 `["acp"]`，不能添加可能绕过 assistant no-tool profile 的启动参数。

## 5. Assistant / Proposal / Worker 与 state v3

运行链路是三层：每 conversation（chat + user）一个无工具 Assistant 会话负责对话与创建 Proposal；唯一活跃 Worker 在 `bot.workspace` 执行已确认 Proposal；Proposal 是两者之间的持久工作单，owner 是 chat + 发起用户，只有发起人本人可 confirm/adjust/follow_up/finish/stop/cancel/list，`start_next` 也只启动发起人自己的 queued Proposal。

Proposal 状态流：`proposed → queued → working → pending → finished`。`proposed` 必须用户确认才进入 `queued`；`pending` 就是「等用户决定」，不区分 success/failure；只有 `finish` 把 pending 落定为 `finished(done)`，`cancel`（proposed/queued/pending）落定为 `finished(cancelled)`；没有 working、owner 自己没有 pending、全局没有 workspaceDirty pending 时，最早确认的 queued Proposal 才可通过 confirm 或 start_next 开始。

Assistant 每条回复以隐藏 `GORI_ASSISTANT_ACTION_V2` envelope 结尾（`reply` + `actions`），action 仅 `create_proposal`、`confirm`、`adjust_proposal`（仅 proposed/queued）、`follow_up`（pending → working，优先 resume 原 worker native session，失败则带 Proposal 上下文新起 session，用户图片附件随 prompt 给 Worker）、`finish`、`send_image`（把 Worker 报告过的 workspace 内图片发给用户）、`start_next`、`cancel`、`stop`，格式错误只修复一次。Worker 每轮以隐藏 `GORI_WORKER_RESULT_V2` envelope 收尾：仅 `PENDING`（`summary` 必填，可选 `question`、`workspaceDirty`、`attachments`），同样只修复一次。envelope 缺闭合标签（模型截断）时先按花括号配平 salvage（字符串/转义感知，配平点必须在文本末尾），失败才进入修复流程。

确认语义：

- Worker 落定即进入 `pending`（记录 summary/question?/workspaceDirty?/receivedAt）；`finish`（可带 note）落定为 `finished(done)`，`cancel` 落定为 `finished(cancelled)`；finished 保留最后 summary 供面板展示。
- 系统不自动开始下一个 Proposal；只有新确认或 `start_next` 推进队列。
- 阻塞规则：任何 `working` 全局拒绝 start_next/follow_up；owner 自己有 pending 时拒绝该 owner 的 start_next（提示先 finish 或 follow_up）；任何 `workspaceDirty: true` 的 pending 全局拒绝 start_next（提示先处理 dirty 工作区）；非 dirty 的 pending 不挡其他用户。
- `stop` 只对 working 生效：停 worker（现有进程组清理）后 Proposal 转为 pending（summary「被用户中止」、workspaceDirty）。
- Assistant 有 pending 时每轮 prompt 注入 pending card；回复没提到 pending 时 runtime 在 reply 末尾追加人话兜底提醒。
- Worker working 期间 runtime 按类别聚合 worker 的 `session/update` 工具活动（turn 开始重置计数；只留类别/时间，不留参数与正文）；Assistant prompt 注入紧凑状态卡（title、mm:ss 时长、最后活动类别与距今、各类别计数、快照指引）。调试期状态卡对所有人可见（他人任务标注 `another user's proposal`），正式运营时应恢复 owner-only。
- Gateway 无固定时间提醒；worker 落定后由 Assistant 生成事件文案发给 owner chat，QQ 无主动消息权限时优先使用被动回复窗口（群 5 分钟/私聊 60 分钟，按 4.5/55 分钟保守判定），过期或失败则不主动发、记录 lastEventDelivery 并在下次入站时补发；`/status` 输出当前 chat 的事件投递状态与 schedulerState/blockedReason/nextAction。

Assistant 隔离：cwd 在实例私有 `state/assistant-workspaces/`，目录 key 使用进程随机 salt 的 HMAC，不得与项目 workspace 重叠；Kimi 项目级 agent override 必须设置 `tools: []`、`subagents: []`，ACP `mcpServers: []`，未显式配置时 `KIMI_CODE_HOME` 指向实例私有 `state/kimi/assistant/`；任何 tool update 或 permission request 都视为隔离违约，fail closed、终止进程组并删除 binding。每个 ACP worker 独立进程组 + 随机 token；runner 重启时 working Proposal 校验 token 清理旧进程组后标记为 pending（worker_lost、workspaceDirty: true）。

state v3（`acp-sessions.json`）header 保存 `botId` 和 platform，只存 assistant binding（agent ID、assistant workspace、native session ID、Bot fingerprint、时间戳）；`proposals.json`（version 2）存 Proposal 记录。state v3 打开时 version/identity 不匹配必须拒绝，不能清空、迁移或覆盖；旧 state v1/v2 也明确拒绝并保留原文件。proposals.json 唯一例外：v1 文件打开时先在同目录写 `proposals.json.v1-<timestamp>.bak`（0600）备份，再按固定映射迁移为 v2（SUCCESS → pending{summary}；FAILED → pending{summary, workspaceDirty: true}；NEEDS_CONFIRMATION → pending{summary, question}；completed/failed → finished(done)（failed 保留失败说明为 finishNote）；cancelled → finished(cancelled)；proposed/queued/working 保留）。fingerprint 包含 bootstrap schema version、Bot ID、workspace/persona/assistantPersona、agent 定义、permission policy、skill 路径和内容 hash。prompt 失败不重放。

命令 `/help`、`/status`、`/list`、`/confirm`、`/finish`、`/stop`、`/cancel` 旁路 Assistant；全部 owner-only（chat + user）：`/confirm` 对 proposed，`/finish` 对 pending，`/stop` 仅对 working（→pending），`/cancel` 对 proposed/queued/pending；`/list` 面板按 pending → working → queued → proposed → 最近 finished 排列。QQ 入站图片附件（image/*，单张 ≤5MB、每条最多 3 张、10 秒下载超时）下载为 base64 经 `IncomingMessage.attachments` 透传；agent 声明 `promptCapabilities.image` 时作为 ACP image content block 发给 Assistant/Worker，否则降级为文本说明；视频/文件附件不下载，仅以 `[视频] <url>` / `[文件] <url>` 文本拼接。

出站图片（QQ）：Worker 在 `GORI_WORKER_RESULT_V2` 的 `attachments`（最多 3 个 `{path, mimeType?}`）上报 workspace 内 png/jpg（建议 `.gori-outbox/`），Assistant 也可用 `send_image { path }` 主动发图；runtime 校验 resolved realpath 必须在 canonical workspace 内、png/jpg magic bytes、单张 ≤10MB，违规丢弃并在事件文本说明。发送走 `POST /v2/{groups|users}/{id}/files` 上传（`file_type: 1` + base64 `file_data` + `srv_send_msg: false`）后 `msg_type: 7` + `media.file_info` 发送；群/私聊上传的 file_info 不通用，按目标分别上传。图片与文本共用 Gateway 的 `msg_id` + 递增 `msg_seq` 计数器；落定事件先文案后图；被动窗口过期时照旧记录并下次入站补发，补发按路径重读文件、文件缺失降级为文本说明；上传/发送失败不阻断文本，降级文本说明 + 安全日志。其他平台 adapter 无 `supportsImages` 标记时图片降级为 `[图片] <文件名>` 文本。

## 6. 单平台装配

Server 只构造 `gateway.platform.type` 对应 adapter，只挂载对应 webhook：

- qq webhook 模式 → `/webhook/qq`；QQ WebSocket 模式不挂载该 route
- feishu → `/webhook/feishu`
- wecom → `/webhook/wecom`
- weixin → `/webhook/weixin`
- webhook → `/webhook/generic`

QQ WebSocket 仅在 qq + websocket 模式启动。`GET /health` 只输出 configVersion、botId、platform 和 aggregate ACP counters，不得输出 credentials 或 native session ID。`GET /platforms` 返回单 Bot/platform 概览。

## 7. 配置与实例施工流程

1. 读取本文件、`config.example.json` 和 `src/config.ts`。
2. 明确 Bot ID、workspace、persona、平台、skills 和最小 permission policy。
3. 确认 ACP agent executable 与 ACP 可用。
4. 使用 `gori-agent init <bot-id>` 或 Coding Agent 生成实例 `config.json`；不要把 example 当运行配置。
5. 交互确认并严格校验 `gateway.server.host/port`；对其他实例的声明端口冲突给出警告和建议，但仍由 `start` 做实际 bind 检查。
6. 写配置必须同目录临时文件 + fsync + atomic rename，最终 `0600`；目录 `0700`。
7. setup 的 secret/token 输入必须不回显；secrets 不在对话、日志、测试输出、diff 中回显。
8. 运行 `gori-agent doctor <bot-id>`，不发送真实平台消息。
9. 只有用户明确授权时才启动/停止真实 Bot。

旧仓库本地 `config.json`、备份和 state 可供人工回退；改造实例时不要删除或覆盖。

## 8. 测试与验收

项目级部署/配置 skill 位于 `.kimi-code/skills/gori-agent-deploy/SKILL.md`；真实 Bot 部署、模型/persona 配置和 state 备份流程以该文件为准。

行为变化补测试，不削弱测试。配置 schema 变化同步：

- `src/config.ts`
- `config.example.json`
- setup/doctor/instance CLI
- README 和本文件
- config、session、store、Gateway、server 测试

最终运行：

```bash
npm run typecheck
npm test
npm run build
git diff --check
bash -n install.sh gori-agent.sh bin/gori-agent
```

额外检查：

- example 可 parse，doctor 识别 placeholder。
- 不存在的运行配置明确失败。
- tracked diff 无 config、backup、state、log、credentials 或手改 dist。
- 不执行真实平台消息、pull、部署、远程机器修改或 Git mutation，除非用户当次明确授权。

## 9. 敏感信息与禁止提交

不得提交或粘贴：

- 任何真实 `config.json` 或备份
- `.env`、agent env token/API key
- platform credentials
- ACP state、PID、lock、session metadata
- 含真实 chat/user/message ID 或消息正文的日志

`.gitignore` 已覆盖仓库本地 `config.json`、备份、日志、`dist`、`node_modules` 和 coverage。实例默认在仓库外。安全性按内容判断，不能只依赖文件名。