9d445c1f65
dev 真机坐实的 agent 挂载法:agent jar(2.29.0,aliyun 镜像直连下)+ JAVA_TOOL_OPTIONS 注 -javaagent 不改 restart 脚本 + OTEL env 指 Collector(traces only、metrics/logs=none 免与面五重复)+ Tempo 见 huijing-server span。 三坑入库:①指标进程内 micrometer 重启清零(Prometheus counter reset,单次 scrape 无累计非 bug) ②watchdog 超时收尸经 handleCallback→面五计 timed_out、迟到重复回调拒绝重入不重计 ③便宜档需续修 gen 延迟可达 20min(gen_duration 埋点量化)。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
.agents/ —— 绘境AI 项目的 Agent 能力中枢
本目录沉淀并复利累积项目的 Agent 能力、知识、规则与流程，让团队在长期跨会话开发中持续抬高 AI 驱动开发的能力、准确率与稳定性。
工作入口、项目定位/目标/目录均见
../AGENTS.md（项目唯一入口）；CLAUDE.md仅以@AGENTS.md导入它。
一、目录结构与职责
| 子目录 | 职责 | 回答的问题 |
|---|---|---|
knowledge/ |
事实与蓝图蒸馏（产品、架构、范围） | 是什么 |
rules/ |
必守的硬约束（工程规范、安全可靠性、build-vs-buy） | 必须怎样 |
skills/ |
可复用操作手册 playbook（怎么做某一类事） | 怎么做 |
workflows/ |
元流程（如何承接、推进、收尾一个任务） | 如何承接任务 |
tools/ |
治理门与文档整理的机械脚本（检测/归档/死链/品牌门） | 机器怎么把门 |
通用顺序：先 knowledge 对齐事实 → 看 rules 划红线 → 用 skills 落地 → 按 workflows 推进收尾。
二、文件清单（每条一句话）
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 签名对齐设计意图 / 运维三硬记） |
mvp-scope-and-milestones.md |
MVP 的 55 项 P0 产品功能范围、5 工位分工、M0-M5 里程碑与验收指标 |
agentscope-2.0-facts.md |
AgentScope 2.0.2 真实架构速查 + 便宜档 cheap-worker 实现 API 速查（免重查）+ 护城河续修/软预算 middleware 的 2.0.2 机制速查（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/ 多文件工程 |
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） |
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 纵切成果切片；诊断信号 + 换轴 + 三层文档 + 必查五坑 |
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 |
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 |
四、维护规则（要点）
- 先查重再新增：全新主题才新建文件；补充/修正既有主题一律更新现有文件，不造重复。
- 过时即处理：信息失效立即修正或删除；与代码/文档冲突时以已验证事实为准。
- 同步索引：任何结构性变更（增/删/改名）同步更新本 README 清单与
../AGENTS.md导航。 - 单一主题、精炼、可检索：每文件聚焦一个主题，用表格与要点，做蒸馏而非照搬源文档。
- 相对路径 + 简体中文：交叉引用用相对路径（仓库迁移不失效）；一律简体中文；死链改
git show <sha>^:<path>定位（见tools/docs-gate.pyG3）。
维护本身是任务收尾的一部分——见
workflows/ai-development-protocol.md的"沉淀"环节与skills/wave-close-checklist.md。