zizi-al/games-development-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
games-development-ai/.agents/README.md
lili 85f48228cd
Some checks failed
contract-gates / contract-gates (push) Has been cancelled
Details
docs-gate / docs-gate (push) Has been cancelled
Details
feat(cheap-gen): W-AXIS 波3 知识层补强+收尾——tsc 顾问门+recipes+暗资产接线+n=5 基线台账 
- tsc 顾问门:typescript devDependency + tsc-advisory 测试档;顾问性(永不阻断),
  金标 10 款零误伤抽验
- recipes/ 五篇高频场景索引(命中矩形/计时器/资产回退/场景机/结算演出,「抄这段形态
  +头号病根」)+ littlejs-game-dev §0.5 卡壳就查接线
- 暗资产接线:plugin-capability-map(11 注入+1 取证+6 储备逐件裁定)+
  engine-capabilities-brief(≤3KB 蒸馏)+ api.d.ts/game-host.d.ts 补插件指针;
  三方一致性对账门 plugin-surface-gate.py(含 cwd 锚定修)挂 pre-commit+Gitea Actions
- hard_genre_batch 参数化(五品类 n=5 批跑驱动,checkpoint 续跑)
- n=5 基线台账入库(gitignore 例外 add -f,只入台账不入游戏产物):
  wax-baseline.jsonl 25 局逐局记录(含判定仪器订正批注:cap1500 重判/图像盲 M3 重判,
  只加字段零改值)——终数:操作口径 14/25=56%、质量口径 18/25=72%;
  品类 narrative/heritage 5/5、trpg 4/5、puzzle/sim-business 2/5(缺口逐局有名有姓,
  根因见 07-10 v2 plan §1);旧「80%/39%」口径正式作废存照

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-10 04:27:18 -07:00

116 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# .agents/ —— 绘境AI 项目的 Agent 能力中枢
> 本目录沉淀并复利累积项目的 **Agent 能力、知识、规则与流程**，让团队在长期跨会话开发中持续抬高 AI 驱动开发的能力、准确率与稳定性。
>
> 工作入口、项目定位/目标/目录均见 [`../AGENTS.md`](../AGENTS.md)（项目唯一入口）；`CLAUDE.md` 仅以 `@AGENTS.md` 导入它。
---
## 一、目录结构与职责
| 子目录 | 职责 | 回答的问题 |
|---|---|---|
| `knowledge/` | 事实与蓝图蒸馏（产品、架构、范围） | **是什么** |
| `rules/` | 必守的硬约束（工程规范、安全可靠性、build-vs-buy） | **必须怎样** |
| `skills/` | 可复用操作手册 playbook（怎么做某一类事） | **怎么做** |
| `workflows/` | 元流程（如何承接、推进、收尾一个任务） | **如何承接任务** |
| `tools/` | 治理门与文档整理的机械脚本（检测/归档/死链/品牌门） | **机器怎么把门** |
> 通用顺序：**先 knowledge 对齐事实 → 看 rules 划红线 → 用 skills 落地 → 按 workflows 推进收尾。**
>
> **与 `.claude/skills/` 的边界（2026-07-05，创始人拍方案①「双层」）**：本目录是项目 playbook 的 **SoT**，全部 skill 带标准 SKILL.md frontmatter（name/description，agentskills.io 规范兼容）；`.claude/skills/` 只放 harness 自动按需加载件——要么独立件（现仅 `agentscope-skill`），要么**薄壳指针**（frontmatter + 一行"读 `.agents/skills/<name>.md` 照其执行"），正文唯一在本目录，防双约定漂移。
---
## 二、文件清单（每条一句话）
**knowledge/**
| 文件 | 一句话说明 |
|---|---|
| `product-and-architecture.md` | 产品定位、13 模块与依赖、三仓三端分层架构蒸馏（中间件 Nacos/RocketMQ/Sentinel 三件套已自托管 mini-infra） |
| `tech-decisions.md` | 技术栈与关键选型 ADR + 待确认项 + 生成主线口径（AgentScope 三档统一收敛）+ 便宜档 M1-M3 实测（§5.1）+ 配置控制面阶段〇/一①② 落地（§10-12）+ 生产 cutover 窗封口（§13：框架默认注入面审计红线 / stuck 签名对齐设计意图 / 运维三硬记）+ 升级 AgentScope 2.0.3（§15：兼容依据 + 原生 Budget/RAG/mem0 列而不迁）+ 内测闭环 A 段落地（§16：new-api per-user 额度预置池 / S0「admin 不能替他人建 token」硬约束 / new-api 权威计量 / 注册防枚举 + facade HMAC 验签） |
| `mvp-scope-and-milestones.md` | MVP 的 55 项 P0 产品功能范围、5 工位分工、M0-M5 里程碑与验收指标 |
| `agentscope-2.0-facts.md` | AgentScope 2.0.3 真实架构速查 + 便宜档 cheap-worker 实现 API 速查（免重查）+ 护城河续修/软预算 middleware 的 2.0.3 机制速查（on_reasoning 拦 finish 续跑 / 洋葱序 / 软预算门判自挂） |
**rules/**
| 文件 | 一句话说明 |
|---|---|
| `engineering-conventions.md` | 命名/分层/API 路径/错误码/提交/PR 等工程规范 + §10 文档治理机器门 |
| `security-and-reliability.md` | 安全基线/幂等/超时重试/合规/可靠性红线（§1 @PermitAll 三条 + §4 外部 IO 不入事务 + §4.1 资金打款） |
| `build-vs-buy.md` | 自研偏误防线 R1-R7：现货尽调前置门/形态终点/约束血统/prior-art 强制步/名义采用禁令/抽象墙审计 |
**skills/**
| 文件 | 一句话说明 |
|---|---|
| `add-business-module.md` | 新增一个 game-module 业务模块的标准步骤 |
| `littlejs-game-dev.md` | AI 写 LittleJS 游戏代码作业手册（code 层）：12 插件 API + 代码结构 + 工厂五法 + 资产/mmx 流 + 受控面铁律，终态产物 = `src/` 多文件工程 |
| `recipes/`（README + 5 篇） | 高频场景落地形态（要做 X→读 Y）：命中矩形/计时器/资产回退/场景机/结算演出，各给「抄这段形态 + 头号病根」；littlejs-game-dev 卡壳时读 |
| `plugin-capability-map.md` | 插件能力图谱：11 注入插件（键/目录/能力/api.d.ts+PLUGIN.md 指针）+ runtime-probe（取证不注入）+ 6 件未注入储备（逐件裁定依据 + 注入触发条件）；机器门 `plugin-surface-gate.py` 的人读台账 |
| `engine-capabilities-brief.md` | 引擎能力 ≤3KB 摘要（从 `game-runtime/docs/ENGINE-CAPABILITIES.md` 蒸馏）：引擎重活已被插件封装、少碰 getEngine + 坐标系 2× 换算坑 |
| `sim-business-game-design.md` | 经营模拟小游戏玩法设计手册（给生成 agent 的设计阶段）：爆款范式/数值/美术/UI/音 → 映射 12 插件 + 反"无趣"8 条自检；与 littlejs-game-dev 配对 |
| `narrative-game-design.md` | 剧情/互动叙事品类设计手册（W-GENRE 件①）：分支选择+多结局图鉴范式 / 文本红线 / 可达性红线含取证契约 |
| `trpg-game-design.md` | TRPG/掷骰冒险品类设计手册（W-GENRE 件①）：掷骰可见 / 风险回报取舍 / 难度爬坡登顶 / 反无趣自检 |
| `heritage-game-design.md` | 非遗/传统技艺品类设计手册（W-GENRE 件①）：工序链玩法化 / 双层奖励 / 文化表述红线 / 反贴皮自检 |
| `puzzle-game-design.md` | 解谜品类设计手册（W-GENRE 件①）：顿悟距离 / 规则递进关卡阶梯 / 卡壳兜底 / 品类可达红线（解映射 targets occupied） |
| `runtime-and-multichannel.md` | 运行时打包、iframe 沙箱、SDK 注入与多渠道（微信/抖音/快手）导出手册 |
| `contract-first-development.md` | 契约先行：8 类契约对齐与各工位 mock 并行解耦 |
| `prompt-governance.md` | Prompt 即第 8 契约：Registry/加载注入/eval 门禁/HITL 治理手册 |
| `wave-close-checklist.md` | 波次收口八步检查单——所有收口铁律指向的唯一可执行清单 |
| `staging-ops.md` | staging 运维配方：机器分工/代码同步/后端重部署/前端构建门/冒烟门/compose 部署 mini-infra |
| `ui-walkthrough-cdp.md` | 真 UI 走查配方（CDP on mini-desktop）：studio/admin 走查 + CDP 七坑 + 信道探针 |
| `game-e2e-cdp-harness.md` | Canvas 游戏 e2e 证据 harness：驱动器六律 + 出厂红线 + 九门真玩（A–G 假绿守卫 + H 机制/latch + I 控制手感） |
| `cheap-model-game-generation.md` | 便宜模型生成跨路通用蒸馏：成本/前缀缓存降本/L1 纪律坑/质量三层/scale-20 模型画像（旧 gamedef/factory 路已压缩留指针，现行走 cheap-worker）+ §11 AgentScope harness 死圈失败模式（小瑕疵→整文件重写→MiniMax 漏 path→stuck 熔断→九门没跑→ok=False；根因实证 2026-07-08） |
| `agentic-amodel-generation.md` | 底层 A-model 生成 harness（`gen.mjs` ReAct 工具循环：scaffold→读写检构→循环外 play）：8 坑 + M3 实证；现行被 cheap-worker shell-out 复用 |
| `gen-path-parity-harness.md` | 两条生成路对照（parity）harness + 按品类 ≥80% 达标门 + auto-vs-golden 双驱动 delta 门：验换实现不回退 / 判够不够格上线 |
| `saa-graph-orchestration.md` | SAA 图编排远期备查（SAA 降最低优先级）：依赖集/接 new-api 剥 /v1 坑/checkpoint saved_at 无 tiebreaker + 显式 checkPointId 修法 |
| `tier2-service-generation.md` | tier2 富游戏服务态生成驱动配方（create_app :8200 + 控制面有界 resume）：真玩 driver 是头号收敛杠杆 + 驱动六口径 + C1 trace |
| `doc-organizer.md` | 文档整理助手（创始人手动触发）：增量窗口 + 两阶段审批门 + 三轴（过期清理/措辞对齐/总账回填）；底层脚本在 tools/ |
| `drive-remote-claude-tmux.md` | 远程驱动交互式 Claude Code（ssh + tmux）：双向通道派活读屏 + 每设备配置 + 完成判据 = git push |
| `architecture-diagram-atlas.md` | 架构图集生成配方：house style / 图说结构 / 三范式纪律（单源·防漂移·状态双层）/ 按域并行编排 / 双评审六坑 |
| `feature-design-doc.md` | 功能设计文档作业手册：WHAT+HOW 合一、一式两份（文字+Mermaid 给人/AI · SVG/HTML 给人）、防漂移单源 |
| `execution-plan-slicing.md` | 执行 plan 切分轴：横切关注面 vs 纵切成果切片；诊断信号 + 换轴 + 三层文档 + 必查七坑 |
| `agentic-seat-context-design.md` | agentic 席位与 context 工程设计需求基线（2026-07-05 模型第一人称探索蒸馏）：四层边界（prompt/context/environment/harness）+ 分席四判据两戒律 + 星形九工件通信 + 注入铁律（模板>门>prompt）+ 长项目六件/版本语义 + goal-loop 交互面 + 设计检查单 + 探针方法附录(§10·W-PROBE) |
**workflows/**
| 文件 | 一句话说明 |
|---|---|
| `ai-development-protocol.md` | 任务承接→分析→评审→执行→验证→沉淀的完整协议 + 子代理 model 成本分档 + §4.2 执行子代理产出验证纪律（DONE 不可信/hash 校验拦造假/自验） |
| `mvp-execution-orchestration.md` | MVP 10-Agent×3 周执行编排 + 8 条复利提效策略 |
**tools/**
| 文件 | 一句话说明 |
|---|---|
| `docs-gate.py` / `docs-gate.sh` | 文档治理机器门（engineering-conventions §10.7）：七检——品牌不变量 / canonical 唯一 / 死链 / 入口卫生 / 留痕隔离 / 设计档申报 / 计划谱系（`上级:` 单指针） |
| `plan-tree.py` | 计划谱系树查询视图（engineering-conventions §10.8）：沿 frontmatter `上级:` 拼树打印，回答「某计划在上线计划的哪个位置 / 某线推进到哪」 |
| `rubric-sync-gate.py` | 品类 rubric fixture ↔ skill 双写对账门（Δ5「无校验器不算契约」执行面）：以 `cheap-worker/fixtures/genre-rubrics/<genre>.json` 为单源，校验各品类 skill 的内联副本名目一致 / 纯指针可达，漂移 exit 1；已挂 pre-commit + Gitea Actions |
| `plugin-surface-gate.py` | 便宜档插件面三方一致性对账门（防漂移）：插件目录 / prompt 白名单（cheap-system.md）/ host-config 注入 + tools.mjs PLUGIN_KEY_DIR 必须对齐，且每个插件目录显式裁定为「注入/取证/储备」之一；漂移 exit 1；已挂 pre-commit + Gitea Actions |
| `doc-organizer.{sh,-analyze.mjs}` + `doc-organizer-state.json` | doc-organizer 底层：检测（scan/health/stale/ledger）+ 可逆归档 + 记时 + 三轴分析 Workflow + 增量窗口锚点 |
---
## 三、按任务类型查阅
| 任务类型 | 先读 | 再读 |
|---|---|---|
| **分析** | `workflows/ai-development-protocol.md` + 相关 `knowledge/` | 原始 `docs/architecture/` 长文档 |
| **评审** | `rules/`（拿约束当尺子）+ `knowledge/` | 对应 `skills/` 看实践标准 |
| **编码** | 对应 `skills/` + `rules/engineering-conventions.md` | `knowledge/` 对齐上下文 |
| **调试** | 相关 `skills/` + `knowledge/` | `rules/security-and-reliability.md` |
---
## 四、维护规则（要点）
1. **先查重再新增**：全新主题才新建文件；补充/修正既有主题一律更新现有文件，不造重复。
2. **过时即处理**：信息失效立即修正或删除；与代码/文档冲突时以已验证事实为准。
3. **同步索引**：任何结构性变更（增/删/改名）同步更新本 README 清单与 [`../AGENTS.md`](../AGENTS.md) 导航。
4. **单一主题、精炼、可检索**：每文件聚焦一个主题，用表格与要点，做蒸馏而非照搬源文档。
5. **相对路径 + 简体中文**：交叉引用用相对路径（仓库迁移不失效）；一律简体中文；死链改 `git show <sha>^:<path>` 定位（见 `tools/docs-gate.py` G3）。
> 维护本身是任务收尾的一部分——见 [`workflows/ai-development-protocol.md`](workflows/ai-development-protocol.md) 的"沉淀"环节与 [`skills/wave-close-checklist.md`](skills/wave-close-checklist.md)。
Reference in New Issue View Git Blame Copy Permalink