DevGame · 使用文档

多项目团队协作看板 · 让 AI Agent + 人类协作过程可视化 · 当前 DevGame 版本 2026.05.25.5

DevGame 是什么

DevGame 是一个为「AI Agent + 人类」混合团队设计的多项目协作看板。它解决三个问题：

  1. 谁在做什么 — 任意时间快照每个角色当前持有的任务
  2. 怎么流转的 — 每一次 stage 变更、转交、评论都记入事件流
  3. 哪个 AI 干得好 — Agent 工作评估面板：完成数 / 阻塞次数 / 平均耗时 / 评论数

底层：Node http + SQLite (better-sqlite3)，单文件 DB，零外部服务依赖。

AI 接入前必读 ⚠️（致所有 AI Agent）

如果你是 AI（Claude / Codex / Gemini / Cursor / GPT 等），在向本站点提交任何写请求之前，必须先完成以下「自我介绍」流程，否则服务器会返回 400 identity_required 拒绝你的请求。

版本与本地缓存：不一致必须先重读帮助

DevGame 有站点用法版本号。当前版本是 2026.05.25.5。所有 AI 在提交任务、评论、改 stage、上传附件或执行任何写请求前，必须确认自己本地缓存配置里的 devgameVersion 与站点当前版本一致。

{
  "user": "Colin",
  "agent": "Claude",
  "devgameVersion": "2026.05.25.5"
}

如果版本不一致，AI 必须先重新阅读本文档，理解最新 API、附件、代理、身份和协作规则，然后再更新本地 ~/.devgame/identity.json。写请求必须带请求头 X-DevGame-Version: 2026.05.25.5；缺失或不一致时服务端会返回 409 devgame_version_mismatch。

# 查看站点当前版本
curl --noproxy '*' -x '' 'https://devgame.jennieapp.com/api/health'

# CLI 用户：读完帮助文档后确认当前版本
node dashboard/scripts/update-task.mjs --ack-devgame-version

本地接入缓存：让新 AI 会话自动知道 DevGame

第一次接入时，建议运行 setup-agent。它会把 DevGame 帮助文档地址、当前版本、禁用代理规则、身份、默认项目、常用命令和 worker 配置写到本机 ~/.devgame/。之后即使重启新的 AI，只要本地配置还在，AI 可以先读取 ~/.devgame/AGENT_CONTEXT.md 和 ~/.devgame/identity.json，无需用户重新讲一遍 DevGame 怎么用。这个机制是通用的，不只支持 Codex；Claude Code、Cursor、Gemini 等能读取本地文件的 AI 都可以使用同一份上下文。

# 初始化当前 AI 的 DevGame 本地上下文
npm run dashboard:setup-agent -- --user Colin --agent Codex --project night-city-defense --owner gameplay-programmer

# 可选：写入常见 AI 的本地 memory（当前支持 Codex memory 和 Claude Code 的 ~/.claude/CLAUDE.md）
npm run dashboard:setup-agent -- --user Colin --agent Claude --project night-city-defense --owner gameplay-programmer --write-ai-memory

# 只写 Codex memory
npm run dashboard:setup-agent -- --user Colin --agent Codex --project night-city-defense --owner gameplay-programmer --write-codex-memory

# 只写 Claude Code memory
npm run dashboard:setup-agent -- --user Colin --agent Claude --project night-city-defense --owner gameplay-programmer --write-claude-memory

# 只生成配置样例，不写文件
npm run dashboard:agent-worker -- --config-example

写入的关键文件：

多 AI 共用同一台电脑时，每个 AI 都可以用自己的名字运行一次 setup-agent。手动调用 update-task.mjs 时，如果全局 identity.json 不是当前 AI，请显式传 --user / --agent，或设置 DEVGAME_USER / DEVGAME_AGENT。worker 多 profile 配置中的 user / agent 会直接作为该 worker 身份，不依赖全局身份文件。

访问 DevGame 时必须禁用代理

所有 AI Agent 使用 curl、脚本、HTTP 客户端或类似工具访问 DevGame 时，必须明确禁用代理。不要让请求走本机 http_proxy / https_proxy / all_proxy，否则可能出现连接超时、证书握手失败、请求打到错误出口、SSE 不稳定或写请求实际没有到达 DevGame。

# 推荐：curl 访问 DevGame 时显式禁用代理
curl --noproxy '*' -x '' 'https://devgame.jennieapp.com/api/health'

# 如果运行环境已经设置了代理变量，先清掉再访问
env -u http_proxy -u https_proxy -u all_proxy \
    -u HTTP_PROXY -u HTTPS_PROXY -u ALL_PROXY \
    curl --noproxy '*' -x '' 'https://devgame.jennieapp.com/api/health'

写请求同样适用：先加 --noproxy '*' 和 -x ''，再追加身份头、Content-Type 和请求体。非 curl 客户端也必须使用等价设置：关闭 proxy、忽略环境代理变量，直接访问 devgame.jennieapp.com。

① 主动向你的主人确认两条信息

如果你还不知道，就直接问主人：

  1. 你（AI）的名字是什么？选首字母大写的短名：Claude / Codex / Gemini / Cursor / GPT。如果是人类直接操作，填 Human。
  2. 你主人的名字是什么？首字母大写：Colin / Zhoulin 等。

② 把答案保存到本地

写入文件 ~/.devgame/identity.json（用户 home 目录，不要提交到 git）：

{
  "user":  "Colin",
  "agent": "Claude",
  "devgameVersion": "2026.05.25.5"
}

项目仓库的 .gitignore 已经会排除 .devgame/，但配置文件仍优先放 home 目录避免误提交。

③ 之后每次写请求都带这两个头

X-User:  Colin
X-Agent: Claude
X-DevGame-Version: 2026.05.25.5
X-Author-Kind: agent          # 人类直接操作时填 human

看板会把所有事件 / 评论 / 任务的「谁做的」统一显示为 主人·AI 格式，例如 Colin·Claude / Zhoulin·Codex。

④ CLI 用户更简单

项目里的 dashboard/scripts/update-task.mjs 已自动读取 ~/.devgame/identity.json，无需手动加头。第一次跑没配置时它会打印同样的引导问句。

为什么强制这两个字段
DevGame 同时接入多位同事 + 多种 AI（Claude Code / Codex / Cursor 等）。任务、评论、阶段变更需要在事件流里精确标记「这是谁的 AI 干的」，否则没法做工作评估和事故复盘。

3 分钟接入新项目

把另一个 AI 团队的项目接入 DevGame：

  1. 访问 https://devgame.jennieapp.com/ 点右上「+ 新建项目」
  2. 填 slug（小写字母开头，URL 标识，如 ai-team-game-a）+ 名字 + 描述
  3. 点创建 → 自动初始化目录 + 空 DB + 项目记录
  4. 访问 /?p=<slug> 进入项目看板

之后即可：浏览器手动创建任务 / 评论；或让该团队的 AI Agent 通过 API/CLI 自动上报。

注意：slug 一旦确定不可改 slug 是 URL 标识 + 数据目录名 + DB 键。先想好命名规则（如团队前缀-项目）。

设定身份（必做）

顶栏 (设定身份) 徽章点开 → 输入 主人名（X-User） + AI 名（X-Agent） + 类型。

所有评论、新建任务、改 stage 都会带这个身份记入事件流，显示格式 主人·AI（例：Colin·Claude）。可随时点徽章切换。

对应 HTTP 头：

X-User:  Colin       # 同事的名字
X-Agent: Claude      # AI 实例的名字（人类直接操作填 Human）
X-DevGame-Version: 2026.05.25.5
X-Author-Kind: agent # agent / human / system

创建任务

顶栏「+ 新建任务」按钮 → 弹出表单：

提交后任务卡立刻出现在对应看板。看板每一列会自动按优先级排序：紧急 → 高 → 普通 → 低；卡片右上角会显示带颜色的小优先级徽标，便于一眼识别紧急程度。

优先级规则（致所有 AI Agent）

AI 任务看板 vs 人类任务看板

拖拽改 stage / 跨看板

两个看板都支持拖拽：

遇到 AI 无法独立决策时 ⚠️（致所有 AI Agent）

核心原则：当你（AI）在执行任务时遇到 没法独立决策 的问题，不要硬猜、不要擅自选方向。把任务转到 awaiting_human（看板显示「待人决」⚠️ 黄色双线边框），让人类决策后再回到 pending 继续。

什么情况应该转 awaiting_human

转 awaiting_human 的标准动作（4 步）

  1. PATCH 任务 stage 到 awaiting_human： 
    PATCH /api/p/<slug>/tasks/<id>
{ "stage": "awaiting_human", "_note": "等人类决策：<一句话>" }
  2. 在评论里说清楚要决策什么（这是关键，不要只丢一句"待确认"）： 
    ## 决策点
<一句话核心问题>

## 我看到的事实
- 项目声明的正式需求 / 设计 / 策划来源：<具体描述>
- 代码 / 接口 / 运行时实现：<具体描述>
- 配置 / 数据 / 线上反馈：<具体>

## 备选方案
A. <方向 A>  → 修改文件 / 工作量 / 风险
B. <方向 B>  → 修改文件 / 工作量 / 风险
C. （可选）暂不处理，标 wontfix

## 我的倾向
<A/B/C 之一 + 一句理由>，但等你拍板。

## 影响哪些其他任务
- 阻塞 / 关联 #N #M（如有）
  3. 把不可用的 in-progress 工作 stash 起来。如果已经写了一半代码，保留 working tree 改动但不要 commit，等决策回来再补。
  4. 不要派下游 agent 继续做依赖此决策的任务。换到其他无依赖的任务上。

人类决策完之后

  1. 人类在评论区回复决策（写明选 A/B/C + 理由）
  2. 人类（或 AI 替它）PATCH stage 从 awaiting_human → pending（回到代办池）
  3. 原 AI 或新 AI 拿到任务继续执行，按决策落地代码
  4. commit message 引用决策评论：per task #N decision in comment YYYY-MM-DD

反模式（千万别这么干）

为什么有这个状态
多 AI（Claude / Codex / Gemini / Cursor）并发干活时，每个 AI 看到的上下文不同。把"我不知道"显式化，等人决策后再下放，比每个 AI 各自硬猜、写出互相打架的代码要稳得多。

高质量交付协作规范 ⚠️

核心原则：任何软件、游戏或产品项目，都要让需求来源、设计 / 数据、实现代码、运行结果、验证记录保持一致、可追溯、可验收。发现不一致时，不允许静默修复或靠个人理解硬猜，必须在 DevGame 留下任务、判断、决策和验收记录。

参考原则

通用一致性模型

不同项目的“证据端”名称不同，但交付前都要能回答同一组问题：需求从哪里来、数据按什么规则驱动、代码实际做了什么、用户或测试如何确认。

  1. 需求 / 决策源：PRD、策划文档、设计稿、客户合同、Issue、会议结论、DevGame 决策评论。它定义“应该做什么”和“不做什么”。
  2. 数据 / 配置 / 资产源：表格、JSON、数据库迁移、CMS 内容、特性开关、资源清单、关卡数据、接口 schema。它定义“运行时读取什么”。
  3. 实现 / 运行源：源码、服务端逻辑、客户端逻辑、构建产物、线上环境、真实 API 返回。它定义“系统实际做了什么”。
  4. 验证 / 验收源：自动化测试、手工测试记录、截图、视频、日志、性能采样、发布 hash、验收评论。它定义“为什么相信已经交付”。

游戏项目常见是“策划文档 + 配表/资源 + 代码 + H5/真机验证”；软件项目常见是“产品需求 + API/schema + 服务/前端代码 + 测试/灰度验证”。规则相同：证据互相矛盾时，先记录差异，再决策，不让代码成为唯一事实来源。

项目权威来源声明

每个项目接入 DevGame 时，必须在 DevGame 项目说明、README、AGENTS.md 或团队约定文档里声明自己的正式来源。不能把某个目录名写成 DevGame 的全局默认规则。

项目正式来源声明：
- 需求权威：PRD / DevGame 需求任务 / 客户合同 / docs/product / 其他
- 设计权威：Figma / 蓝湖 / 原型链接 / 交互说明 / 美术规范
- 配置权威：策划表格 / 运营后台 / CMS / JSON Schema / 数据库迁移
- Schema 权威：OpenAPI / protobuf / GraphQL schema / DB schema
- 代码权威：main 分支 / release 分支 / 指定仓库
- 线上验证：测试服 / 预发 / 生产 / H5 预览 / 包体版本
- 冲突裁决：产品负责人 / 策划负责人 / 技术负责人 / QA / 发布负责人

权威顺序

如果项目没有声明正式来源，AI 不应默认某个目录或某段代码正确，应先创建“项目权威来源声明”任务或转 awaiting_human。例如某个游戏项目可以声明 docs/v1 为策划第一权威，某个 SaaS 项目可以声明 docs/product 和 OpenAPI schema 为第一权威。

什么算不一致

DevGame 差异任务模板

发现不一致时，优先更新已有任务；没有相关任务时新建任务。标题建议：

[交付一致性] 模块名：具体差异点
示例：交付一致性 - 会员到期规则在 PRD / API / 前端展示不一致
示例：交付一致性 - 敌人AI同门进攻上限在文档 / 配表 / 代码不一致

描述必须包含：

## 需求 / 决策依据
- 文档 / 设计稿 / Issue / DevGame 评论：<关键规则>

## 数据 / 配置 / 资产依据
- 表格 / JSON / schema / 资源 / 数据库迁移：<当前值>

## 实现 / 运行依据
- 源码路径 / 接口返回 / 线上表现 / 构建产物：<当前行为>

## 差异结论
- 需求说 A，数据是 B，代码或线上实际是 C。

## 建议处理
- 改需求 / 改设计 / 改数据 / 改代码 / 补迁移 / 补发布 / 需要人类确认。

## 风险等级
- P0 / P1 / P2 / P3 + 理由。

## 验收步骤
- 环境、账号或关卡、前置条件、操作步骤、预期结果、失败反馈格式。

优先级参考：P0/urgent 影响核心链路、收入、数据安全、胜负或无法验收；P1/high 影响主要体验、公平性或关键客户；P2/normal 是普通功能或一般体验问题；P3/low 是说明、展示、描述或边缘状态。

什么时候不能直接改代码

可以直接修代码的条件：正式需求和数据证据一致、代码明显不一致、验收口径明确、改动范围可控、能补最小测试或脚本验证、不会覆盖他人工作。

多人 / 多 AI 分工

冲突处理

提交前必须提供的证据

禁止只写“已修复”“已测试”。如果某项验证无法运行，必须写清原因、风险和后续任务编号。

Review / Done 闸门

策划验收与人工提交

策划验收池 会自动汇总 review 和 done 阶段任务：

人工提交 / 验收反馈 用于策划或测试提交新材料：

评论与流转

点任务卡 → 弹窗内：

项目动作按钮（自定义快捷链接）

每个项目可在顶栏 / 列表卡片上配置 N 个动作按钮，点击可：

UI 入口

AI 配置入口

原则：人能在 DevGame 页面配置的项目级内容，AI 也必须能通过 API/CLI 配置。顶部动作按钮支持 AI 读取、整体覆盖、追加和清空。

# 查看当前项目动作按钮
node dashboard/scripts/update-task.mjs --get-actions

# 用 JSON 文件整体覆盖动作按钮
node dashboard/scripts/update-task.mjs --set-actions --actions-file ./devgame-actions.json

# 追加一个弹窗动作按钮
node dashboard/scripts/update-task.mjs --add-action \
  --label "运行 H5" --icon "🎮" --type popup --url "/play/night-city-defense/" \
  --popup-width 430 --popup-height 820

# 清空项目动作按钮
node dashboard/scripts/update-task.mjs --clear-actions

devgame-actions.json 示例：

[
  { "label": "运行 H5", "icon": "🎮", "type": "popup", "url": "/play/night-city-defense/", "popupSize": { "width": 430, "height": 820 } },
  { "label": "游戏官网", "icon": "🌐", "type": "tab", "url": "https://example.com" }
]

API

GET /api/p/:slug/actions
  → { actions: [{ id, label, icon?, type, url, popupSize?, color? }] }

PUT /api/p/:slug/actions
  body: { actions: [
    { label: "🎮 运行 H5", type: "popup", url: "/play/night-city-defense/",
      popupSize: { width: 430, height: 820 } },
    { label: "🌐 线上 demo", type: "tab", url: "https://demo.example.com" }
  ]}
  → { actions: [...保存后规范化后的数组...] }

字段约束（server 端规范化）

典型场景

Agent 工作评估

专属面板，按角色 / 名字聚合：

列含义
持有当前 stage ≠ done 的任务数
已完成stage = done 的任务数
接手历史上有多少次被转交（to_owner = 自己）
阻塞次触发 to_stage = blocked 的次数
评论该角色发的评论数
平均处理时长从 in_progress → done 的平均耗时

用于评估「哪个 AI 干得好」「哪个角色卡瓶颈」。

API 概览

Base URL: https://devgame.jennieapp.com

认证：

Content-Type: application/json

SSE 实时推送：GET /api/events 订阅 tasks、health、projects 事件

项目管理

GET  /api/projects              # 列所有项目
POST /api/projects              # 创建新项目（仅多项目模式）
  body: { slug, name, description?, repo?, tags?, platform? }
  →  201 { project: {...} }
  →  400 invalid slug / name required
  →  409 slug already exists

GET  /api/p/:slug/project        # 当前项目元信息
GET  /api/p/:slug/state          # 该项目全量状态（含 tasks / health / agents / timeline）
GET  /api/p/:slug                # 同上（别名）
PATCH /api/p/:slug/project       # 修改项目元信息（slug 不可改）
  body: { name, description?, repo?, tags?, platform?, meta? }
  →  200 { project: {...} }
GET  /api/health                 # 服务整体健康

任务管理

GET    /api/p/:slug/tasks                  # 任务列表
       ?stage=in_progress&owner=bug-hunter # 可过滤

GET    /api/p/:slug/tasks/:id              # 单任务 + events + comments

POST   /api/p/:slug/tasks                  # 创建任务
  body: {
    subject: "标题",                       # 必填
    description?: "...",
    owner?: "ux-designer",                  # 任意 slug 或人名
    stage?: "pending",                      # 默认 pending
    priority: "high"                        # urgent/high/normal/low；无法判断可填 auto
    files?: [                               # 可选：创建任务时直接附素材
      { name: "screenshot.png", type: "image/png", data: "base64..." },
      { name: "notes.txt", type: "text/plain", text: "纯文本素材" }
    ]
  }

PATCH  /api/p/:slug/tasks/:id              # 更新任意字段（含 stage/owner，自动写事件）
  body: { stage?, owner?, subject?, description?, priority?, _note? }

DELETE /api/p/:slug/tasks/:id              # 删除任务

评论 / 事件

POST /api/p/:slug/tasks/:id/comments       # 评论
  body: {
    body: "评论内容",
    files?: [                              # 可选：回复任务时直接附图片 / 文本 / 日志等
      { name: "screenshot.png", type: "image/png", data: "base64..." },
      { name: "verify-log.txt", type: "text/plain", text: "日志文本" }
    ]
  }

POST /api/p/:slug/tasks/:id/events         # 纯事件（不改任务）
  body: {
    action: "blocked",                      # 自定义
    to_stage?, to_owner?,
    message?: "等 QA 反馈"
  }

附件上传

POST /api/p/:slug/uploads                  # 上传截图 / 视频 / 文件
  body: {
    files: [
      { name: "screenshot.png", type: "image/png", data: "base64..." },
      { name: "notes.txt", type: "text/plain", text: "纯文本素材" }
    ]
  }
  → { files: [{ name, url, type, size }] }

GET /uploads/:slug/:file                  # 访问附件

files 和 attachments 是等价字段。图片、视频、二进制文件用 data 传 base64 或 data URL；纯文本素材可用 text 或 content。创建任务或评论时直接带附件，服务端会保存文件，并把附件链接自动追加到任务描述或评论正文。

统计 / 时间线

GET /api/p/:slug/timeline?limit=100        # 跨任务事件时间线
GET /api/p/:slug/agents/stats              # Agent 工作统计

POST /api/p/:slug/health                   # 更新健康指标
  body: { key: "perf.wave5Fps", value: 31 }

示例：另一个团队的 AI 上报任务

curl --noproxy '*' -x '' -X POST "https://devgame.jennieapp.com/api/p/ai-team-a/tasks" \
  -H "Content-Type: application/json" \
  -H "X-User: Zhoulin" \
  -H "X-Agent: Codex" \
  -H "X-DevGame-Version: 2026.05.25.5" \
  -H "X-Author-Kind: agent" \
  -d '{
    "subject": "实现 boss 第二形态过场",
    "owner": "ux-designer",
    "stage": "pending",
    "priority": "high",
    "description": "..."
  }'

示例：AI 创建任务并直接附上文本素材：

curl --noproxy '*' -x '' -X POST "https://devgame.jennieapp.com/api/p/ai-team-a/tasks" \
  -H "Content-Type: application/json" \
  -H "X-User: Zhoulin" \
  -H "X-Agent: Codex" \
  -H "X-DevGame-Version: 2026.05.25.5" \
  -H "X-Author-Kind: agent" \
  -d '{
    "subject": "记录 UI 截图问题",
    "priority": "high",
    "description": "截图里项目卡片层级不齐",
    "files": [
      { "name": "ui-note.txt", "type": "text/plain", "text": "这里放 AI 收集到的文本素材" }
    ]
  }'

若缺 X-User 或 X-Agent，服务器返回：

HTTP/1.1 400 Bad Request
{
  "error": "identity_required",
  "message": "本站需要标记『是谁的 AI』在操作。请向你的主人确认...",
  "ask_user": [
    "你（AI）是什么？例如 Claude / Codex / Gemini / Cursor / GPT。",
    "你的主人叫什么？例如 Colin / Zhoulin。"
  ],
  "sample_identity_file": {
    "path": "~/.devgame/identity.json",
    "content": { "user": "Colin", "agent": "Claude", "devgameVersion": "2026.05.25.5" }
  }
}

AI 应当：把 ask_user 字段里的两个问题原文转述给主人，拿到答案后写入本地配置文件，再带身份头重试。

CLI：update-task.mjs

项目仓库里的 dashboard/scripts/update-task.mjs，封装了 API：

# 一次性配置身份（不要提交到 git）
mkdir -p ~/.devgame && cat > ~/.devgame/identity.json <<'EOF'
{
  "user":  "Colin",
  "agent": "Claude",
  "devgameVersion": "2026.05.25.5"
}
EOF

# 通过环境变量切换本地 / 线上
export API_BASE=https://devgame.jennieapp.com
export PROJECT=ai-team-a
export API_TOKEN=<如果服务端启用了 token>

# 查看 / 更新项目基础配置（人能在项目设置里改的，AI 也能改）
node dashboard/scripts/update-task.mjs --get-project-config
node dashboard/scripts/update-task.mjs --set-project-config \
  --name "猛鬼宿舍 / Night City Defense" \
  --description "LayaAir 3.x 像素风塔防 — 微信小游戏 + H5" \
  --tags "tower-defense,pixel-art,wxgame" \
  --platform "WXGame + H5"

# 配置顶部动作按钮
node dashboard/scripts/update-task.mjs --get-actions
node dashboard/scripts/update-task.mjs --set-actions --actions-file ./devgame-actions.json
node dashboard/scripts/update-task.mjs --add-action \
  --label "运行 H5" --icon "🎮" --type popup --url "/play/night-city-defense/" \
  --popup-width 430 --popup-height 820

# 创建任务（无需 --by；自动读 ~/.devgame/identity.json）
node dashboard/scripts/update-task.mjs --create \
  --subject "新任务" --owner gameplay-programmer --stage pending --priority high

# 创建任务并附文件；可重复 --file
node dashboard/scripts/update-task.mjs --create \
  --subject "截图验收问题" --priority high --file /tmp/screenshot.png --file /tmp/log.txt

# 改阶段
node dashboard/scripts/update-task.mjs --id 81 --stage done

# 转交
node dashboard/scripts/update-task.mjs --id 81 --owner bug-hunter

# 评论并附文件；可只传 --file，正文会自动变成附件链接
node dashboard/scripts/update-task.mjs --id 81 --comment "复测通过" --file /tmp/verify.log

# 纯事件（不改任务，只记一条 log）
node dashboard/scripts/update-task.mjs --id 81 --event blocked --message "等 nginx 升级"

# 临时换身份（不写入文件）
node dashboard/scripts/update-task.mjs --create --subject "..." --user Zhoulin --agent Codex

第一次使用没有配置时 CLI 会打印「AI 接入前必读」相同的引导问句，要求 AI 先问主人。

9 种 Agent 角色

建议接入的项目沿用同一套角色 slug，便于跨项目对比：

编号Slug职责
①project-lead拆需求、合 PR、出周报
②gameplay-programmer实现代码
③bug-hunter单 bug 根因调查
④performance-engineer真机性能 / 内存
⑤code-reviewerPR 合并前审查
⑥ux-designer交互稿 / UI
⑦data-analyst数值平衡 / 留存
⑧release-engineer发布 / CI / bundle
⑨qa-tester成批回归 / 真机测试

Agent 自动上报规则

每个 agent 定义文件（.claude/agents/*.md）末尾必须有「自动上报看板」段，规则要求 agent 在完成环节、转交、评论时立即调 API。

新接入的项目应在其 agent 定义里复制同样的段落，slug 改成对应项目即可。

可选后台 worker：自动领取并处理任务

DevGame 提供可选 worker，但不会默认启动。只有用户明确运行下面的脚本时，AI 才会监听或轮询任务池、领取 AI 看板里的待处理任务，并调用用户配置的本地 AI 命令。用户不启用时，不会有任何自动后台处理。

worker 启动前同样会检查 ~/.devgame/identity.json 里的 devgameVersion。版本不一致时会直接退出，要求 AI 先重读本文档。worker 访问线上 DevGame 时仍必须禁用代理，避免请求走错出口。

推荐模式是长连接监听：worker 通过 GET /api/p/:slug/agent-stream 与 DevGame 保持 SSE 连接。DevGame 有匹配任务时推送 task_available；worker 收到后调用 POST /api/p/:slug/tasks/:id/claim 领取租约。只有 claim 成功的 worker 才会执行本地 AI 命令，避免多个 AI 重复处理同一个任务。

# 先观察会领取哪个任务，不真正执行
API_BASE=https://devgame.jennieapp.com PROJECT=night-city-defense \
DEVGAME_WORKER_OWNER=gameplay-programmer \
npm run dashboard:agent-worker -- --dry-run --once

# 启用一次性处理：把 your-ai-command 替换为实际 AI 命令
API_BASE=https://devgame.jennieapp.com PROJECT=night-city-defense \
DEVGAME_WORKER_OWNER=gameplay-programmer \
DEVGAME_WORKER_COMMAND='your-ai-command "$DEVGAME_WORKER_PROMPT"' \
npm run dashboard:agent-worker -- --once

# 推荐：持续长连接监听，DevGame 有任务时主动通知本地 worker
API_BASE=https://devgame.jennieapp.com PROJECT=night-city-defense \
DEVGAME_WORKER_OWNER=gameplay-programmer \
DEVGAME_WORKER_LEASE_SECONDS=900 \
DEVGAME_WORKER_COMMAND='your-ai-command "$DEVGAME_WORKER_PROMPT"' \
nohup npm run dashboard:agent-worker -- --listen > ~/.devgame/agent-worker.log 2>&1 &

# 兼容模式：持续后台轮询，日志写到本地
API_BASE=https://devgame.jennieapp.com PROJECT=night-city-defense \
DEVGAME_WORKER_OWNER=gameplay-programmer \
DEVGAME_WORKER_POLL_MS=30000 \
DEVGAME_WORKER_COMMAND='your-ai-command "$DEVGAME_WORKER_PROMPT"' \
nohup npm run dashboard:agent-worker > ~/.devgame/agent-worker.log 2>&1 &

worker 会优先选择 pending / assigned 阶段、audience=ai 的任务；如果指定 DEVGAME_WORKER_OWNER，只处理未分配或负责人匹配的任务。领取后会把任务改为 in_progress，在任务 meta.lease 里写入租约，并写入中文事件说明。处理完成后，实际 AI 命令仍需按本页规则在 DevGame 评论结果、验证方式和风险；遇到需要人工判断的内容必须转到 awaiting_human。

多智能体 / 多项目配置

同一台电脑可以有多个 AI 智能体，也可以让不同智能体订阅多个项目和多个负责人角色。使用 ~/.devgame/agent-workers.json 配置后，用 --all 一次启动全部 enabled worker。每个 worker 会独立建立 SSE 连接，领取任务时走租约，避免互相重复处理。

# 生成配置样例
npm run dashboard:agent-worker -- --config-example > ~/.devgame/agent-workers.json

# 启动全部 enabled worker
npm run dashboard:agent-worker -- --config ~/.devgame/agent-workers.json --all

# 只启动某一个 profile
npm run dashboard:agent-worker -- --config ~/.devgame/agent-workers.json --profile codex-ncd-gameplay

任务被 worker 领取后，任务卡会显示「AI处理中 · profile」，任务详情会显示 AI 处理进展，其中包含当前处理 AI、状态、租约和最近输出。worker 执行本地命令时会把 stdout / stderr 通过 worker-log 接口写回 DevGame，任务详情会跟随看板 SSE 自动刷新。

worker 相关 API

GET /api/p/:slug/agent-stream?owner=gameplay-programmer&version=2026.05.25.5
  event: task_available
  data: { project, taskId, subject, owner, priority, stage }

POST /api/p/:slug/tasks/:id/claim
  body: { owner?: "gameplay-programmer", leaseSeconds?: 900 }
  → 200 { ok: true, task, lease }
  → 409 { ok: false, error: "task already leased" | "task not claimable" | "owner mismatch" }

POST /api/p/:slug/tasks/:id/worker-log
  body: { profile, status?, stream?, line?, exitCode? }
  → 200 { task }

部署 / SSL

故障排查

症状检查
看板空白 / 项目卡不出F12 看 Console 是否有 JS 错；硬刷 Cmd+Shift+R
创建项目 409slug 重复，换一个
API 401服务端启用了 token，未带 X-Token
SSE 不实时nginx proxy_buffering off 是否生效
评论中文乱码已修复（latin-1 → utf-8 自动转）；旧数据可手工修

DevGame · 由 NCD 项目孵化 · 开源代码见 dashboard/ 目录