lili 85f48228cd

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

12 KiB

Raw Blame History

.agents/ —— 绘境AI 项目的 Agent 能力中枢

本目录沉淀并复利累积项目的 Agent 能力、知识、规则与流程，让团队在长期跨会话开发中持续抬高 AI 驱动开发的能力、准确率与稳定性。

工作入口、项目定位/目标/目录均见 ../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`

四、维护规则（要点）

先查重再新增：全新主题才新建文件；补充/修正既有主题一律更新现有文件，不造重复。
过时即处理：信息失效立即修正或删除；与代码/文档冲突时以已验证事实为准。
同步索引：任何结构性变更（增/删/改名）同步更新本 README 清单与 ../AGENTS.md 导航。
单一主题、精炼、可检索：每文件聚焦一个主题，用表格与要点，做蒸馏而非照搬源文档。
相对路径 + 简体中文：交叉引用用相对路径（仓库迁移不失效）；一律简体中文；死链改 git show <sha>^:<path> 定位（见 tools/docs-gate.py G3）。

维护本身是任务收尾的一部分——见 workflows/ai-development-protocol.md 的"沉淀"环节与 skills/wave-close-checklist.md。

12 KiB Raw Blame History Unescape Escape