9fe50a4fee
便宜档九门基线诊断后,治创始人选的剩两层:
- 层1 生成幻觉:M3 对插件参数形状/返回值幻觉(drawButton 返 void 误赋值、
sceneFsm.define 单对象批量),check 门只查方法名存在 → 带病过 check+build+smoke。修:
· prompt.mjs + littlejs-game-dev.md 补两条 footgun 正反例(drawButton 返 void、
命中用 pointInRect;define 逐场景调)
· tools.mjs check 加形状静态门(拦 drawButton 返回值赋值 + define 单对象批量)
- 层2 链路假绿:stage 不产 play-spec → 裸跑 driven=false → E/H 降 advisory → 假绿。修:
· tools.mjs ensurePlaySpec 据 _forensicsView 形态自动推 driver(有 targets→tap-targets/否则 key-cycle)
· play.mjs smokeBoot 抓 _forensicsView().state();gen.mjs done 门 smoke 绿后调用
验证(vf-* 干净重跑):
- check 形状门对 base1/4/5 好游戏零误伤、对 base2/3 幻觉精准命中
- vf-mole 打地鼠(base2 同类):卡menu/E·G·H挂 → 九门全过、进 play(drawButton 幻觉治好)
- vf-2048 合成(base3 同类):define 已写对(幻觉治好);仍卡 menu = 新发现 key-cycle driver
缺起局点击(menu 用 tap、play 用 key)= 第三层 driver bug、非本两层,下一步小修
- 两款 playspec 自动产、driven=true(假绿终结)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
.agents/ —— 绘境AI 项目的 Agent 能力中枢
本目录沉淀并积累项目的全部 Agent 能力、技能与规则，让团队在长期开发中复利式积累知识、流程与能力，持续提升 AI 驱动开发的能力、准确率与稳定性。
工作入口、项目定位/目标/目录均见
../AGENTS.md（项目唯一入口）；CLAUDE.md仅以@AGENTS.md导入它。
一、本目录是什么
随着项目长期、跨会话推进，零散的认知和踩坑很容易丢失，AI 每次都"从零理解"。.agents/ 把这些沉淀成结构化、可检索、可复用的资产：事实蒸馏、硬约束、操作手册、元流程各归其位。每次任务从这里取经验、向这里存经验，能力随时间累积而非反复重置。
二、目录结构与职责
| 子目录 | 职责 | 回答的问题 |
|---|---|---|
knowledge/ |
事实与蓝图的蒸馏（产品、架构、范围、术语） | 是什么 |
rules/ |
必须遵守的硬约束（工程规范、安全可靠性） | 必须怎样 |
skills/ |
可复用操作手册 playbook（怎么做某一类事） | 怎么做 |
workflows/ |
元流程（如何承接、推进、收尾一个任务） | 如何承接任务 |
完整文件清单
knowledge/
| 文件 | 一句话说明 |
|---|---|
knowledge/product-and-architecture.md |
产品定位、13 模块与依赖、三仓三端架构蒸馏 |
knowledge/tech-decisions.md |
技术栈与关键选型理由 |
knowledge/mvp-scope-and-milestones.md |
MVP 的 55 项 P0 产品功能范围、里程碑与验收指标 |
knowledge/glossary.md |
术语表 |
knowledge/agentscope-2.0-facts.md |
AgentScope 2.0.2 真实架构速查（tier2 agentic 底座 · 3 路源码实证，免重查） |
rules/
| 文件 | 一句话说明 |
|---|---|
rules/engineering-conventions.md |
命名/分层/API 路径/错误码/提交/PR 等工程规范 |
rules/security-and-reliability.md |
安全基线、幂等、超时重试、合规与可靠性约束（§1 含「@PermitAll 公开读端点纪律」三条：裁字段/DataPermission/租户 scoping，P-OPN-08 实证；§4 含「外部 IO 一律不入 DB 事务」泛化红线 + §4.1 资金打款特例） |
rules/build-vs-buy.md |
自研偏误防线(R1-R7):现货尽调前置门/形态终点测试/约束血统/prior-art 强制步/名义采用禁令/抽象墙审计 |
skills/
| 文件 | 一句话说明 |
|---|---|
skills/add-business-module.md |
新增一个 game-module 业务模块的标准步骤 |
skills/add-game-template.md |
新玩法模板接入配方（契约→prompt→runtime→后端→编排器→五级验收门，merge 实战收口版） |
skills/littlejs-game-dev.md |
AI 直接写 LittleJS 游戏代码作业手册(code 层)：12 插件 API 速查(8 基元 + 4 编排=session-score/hud-ui/scene-fsm/timer-scheduler) + 可导航代码结构 + 写 WHAT 调 HOW 边界 + 资产/mmx 流 + 工厂五法契约 + 受控面铁律（终态产物=src/ 多文件工程，取代废弃的 gameDefinition JSON 投影线） |
skills/sim-business-game-design.md |
经营模拟小游戏玩法设计作业手册(给 SAA design 层)：放置/经营/养成爆款范式(玩法/机制/进度/数值/美术/UI/音)→ 映射 A-model 12 插件可达子集 + design 层输出配方 + 反"无趣"8 条自检；与 littlejs-game-dev(code 层)配对 |
skills/runtime-and-multichannel.md |
运行时打包、沙箱、SDK 与多渠道导出手册 |
skills/contract-first-development.md |
契约先行：契约对齐与并行解耦 |
skills/prompt-governance.md |
Prompt 即第 8 契约：Registry/加载注入/eval 门禁/HITL 治理手册 |
skills/wave-close-checklist.md |
波次收口八步检查单——所有收口铁律指向的唯一可执行清单（第 8 步=spec 退役/分层 + docs/agent-specs/_index.md 维护） |
skills/staging-ops.md |
staging 运维配方：机器分工/代码同步/后端重部署/前端构建门/冒烟门 |
skills/ui-walkthrough-cdp.md |
真 UI 走查配方（CDP on mini-desktop）：studio/admin 走查 + CDP 七坑 + 信道探针 |
skills/game-e2e-cdp-harness.md |
Canvas 游戏 e2e 证据 harness：编排形制/驱动器六律/出厂红线/四件套口径（T1b-α 实证；§7 = W-G1 生成游戏真玩九门 = 假绿守卫 G 门 + H 机制/latch + I 控制手感 + 自产 gatespec） |
skills/cheap-model-game-generation.md |
便宜模型（new-api DeepSeek/MiniMax）直出可真玩轻游戏 L1 worker：链路/模型与成本/L1 纪律/坑红线/latch 套壳/design agent 自产 gatespec/质量三层（W-G1 HJ-GEN-001 实证）。注：A-model 路改用下条 agentic harness，本条 gamedef/worker-loop 部分已退役 |
skills/agentic-amodel-generation.md |
agentic A-model 生成 harness（ReAct+M3 已实证·生产形态）：scaffold→工具循环（read/write/list/check/build/done）→循环外 play；链路/5 文件/运行配方/8 坑（write 前缀·compaction·停机纪律·防假绿·bundle.tick·boot envelope·路径深度）/M3 3-玩法自闭环实证/主流定性；取代旧 gamedef 单次产线（HJ-AGI-003） |
skills/saa-graph-orchestration.md |
SAA（Spring AI Alibaba）裸 StateGraph 生成编排：拓扑/加节点/接 new-api(剥 /v1 坑)/checkpoint(含 saved_at 无 tiebreaker 框架坑+显式 checkPointId 修法)/observation/最小依赖集/派发契约/验证门（HJ-AGI-002 实证） |
skills/doc-organizer.md |
文档整理助手（创始人手动触发）：增量(上次清理→现在)+两阶段审批门——发起分析 Workflow→编清理计划→评审→批准后才执行；三轴=过期档清理(归档/压缩)/核心设计档措辞对齐现行真相/主任务总账回填；底层 tools/doc-organizer.{sh,-analyze.mjs,-state.json}（检测自动·判断留人·脚本不自删·最新日在飞档不碰） |
skills/drive-remote-claude-tmux.md |
远程驱动交互式 Claude Code（ssh + tmux）：双向通道 send-keys 派活 + capture-pane 读屏，不走 ACP/headless；每设备配置块 + onboarding 侦察配方 + 专用会话(独立 worktree 防撞树) + bypass-perms + 安全红线；完成判据=git push 非读屏（创始人 2026-06-18 拍板·多设备复用） |
skills/architecture-diagram-atlas.md |
架构图集生成配方：house style 规格 / 图说文档结构(金样板) / 三范式纪律(单源·防漂移门·状态双层) / 按域并行编排(克隆金样板·结构化返回) / 复验脚本 / 双评审揪出的六坑(漏域·现行远期错标·缺状态列·契约画理想·凑数配额·复制Mermaid漂移) / 分两期+跨session协调(生成引擎子树归在飞线只链不画)（2026-06-22 第一期实证） |
skills/feature-design-doc.md |
功能设计文档作业手册：取代 agent-specs review/execution 双档；一份文档 WHAT(意图/目标/边界/验证)+HOW(方案/步骤)合一；一式两份(文字+Mermaid 给人/AI · SVG/HTML 给人更重要、看图即懂)；复用 atlas house style + 防漂移单源(文字为准) + 媒介分工(md 直渲 Mermaid/SVG · HTML 链接打开)（2026-06-24 创始人定） |
workflows/
| 文件 | 一句话说明 |
|---|---|
workflows/ai-development-protocol.md |
任务承接→分析→评审→执行→验证→沉淀的完整协议 |
workflows/mvp-execution-orchestration.md |
MVP 10-Agent×3周 执行编排 + 8 条复利提效策略 |
三、使用方式（按任务类型查阅）
| 任务类型 | 先读 | 再读 |
|---|---|---|
| 分析 | workflows/ai-development-protocol.md + 相关 knowledge/ |
原始 docs/architecture/ 长文档 |
| 评审 | rules/（拿约束当尺子） + knowledge/ |
对应 skills/ 看实践标准 |
| 编码 | 对应 skills/（操作手册） + rules/engineering-conventions.md |
knowledge/ 对齐上下文 |
| 调试 | knowledge/glossary.md + 相关 skills/ |
rules/security-and-reliability.md（排查可靠性/幂等问题） |
通用顺序：先 knowledge 对齐事实 → 看 rules 划红线 → 用 skills 落地 → 按 workflows 推进与收尾。
四、维护规则（关键）
.agents/ 的价值取决于是否被持续、规范地维护。务必遵守：
- 何时新增 vs 更新现有
- 出现全新主题（新模块手册、新流程）→ 新增文件。
- 是对已有主题的补充/修正→ 更新现有文件，不要另起炉灶造重复。
- 先查重：新增前先检索本目录，避免重复条目和同义文件。
- 过时即处理：信息失效时立即修正或删除，不留误导性内容；与代码/文档冲突时以已验证事实为准。
- 单一主题、精炼、可检索：每个文件聚焦一个主题，用表格与要点，便于 Agent 快速定位；避免照搬源文档大段内容，做蒸馏与索引。
- 同步索引与交叉链接：任何对
.agents/的结构性变更（增/删/改名文件），都要同步更新本 README 的清单，以及../AGENTS.md中相关导航与交叉链接，保持全局一致。 - 语言：一律使用简体中文。
- 相对路径链接：文件间交叉引用使用相对路径，保证仓库迁移后链接不失效。
维护本身就是任务收尾的一部分——见
workflows/ai-development-protocol.md的"沉淀"环节。