@misakiwww/gmod-vibe-coding

v0.2.3

Published

3 months ago

Generic AI-coding collaboration harness skeleton (Trellis workflow + cross-platform agents/skills/hooks). GMod profile, GitNexus, and MCP integrations are layered on by separate add scripts.

0High
0Medium
0Low

misakiwww

trellis ai-coding harness skeleton claude-code cursor codex opencode

gmod-vibe-coding

English | 中文

基于 Trellis 工作流的 AI 编程协作脚手架。提供多平台（Claude Code、Codex）的 agents、skills、hooks 与任务流程，可选叠加代码理解（GitNexus）、GMod profile、证据研究工具。

npm install → npx gmod-vibe-coding-init → 在新项目或已有项目上叠加协作骨架（默认不覆盖已有文件）。

特性

Trellis 工作流：Plan / Execute / Finish 三阶段，需求、实现、验收各步有对应 agent 与产物（prd / design / implement / spec / wiki）
多平台：agents/skills 同步到 Claude Code（.claude/）与 Codex / Gemini CLI / Pi / Kimi Code（共享 .agents/skills/）；hooks 双平台自动接入——Claude Code（.claude/hooks/）+ Codex（.codex/hooks/ + .codex/hooks.json，5 事件对等：SessionStart / UserPromptSubmit / SubagentStart / Stop / PreToolUse）。Codex 首次运行需 trust 项目，否则项目级 hooks 不加载（hooks GA + 默认开，无需改 config.toml）。
代码理解：GitNexus 构建代码图谱，支持调用关系（context）、改动影响（impact）、执行流检索（query）、路径追踪（trace）；GMod 项目追加 gmod_scope / gmod_routes / gmod_metatype
任务分工：9 个 agent 按角色分工（brainstorm / wireframe / research / review / implement / check / spec-wiki-writer / commit-drafter / gmod-explore），主会话调度，各 agent 独立上下文
GMod profile（可选）：GMod 专用 agent、L1 测试统一入口（l1_check.py 分发 LuaLS / Rust sim 引擎 / 契约 lint）、部署与热更新（deploy_orchestrator）、护栏规则 G1-G11
证据研究（可选）：smart-search 多源网络检索，assay 管理证据与架构决策

快速开始

# 新项目
mkdir my-project && cd my-project && npm init -y
npm install @misakiwww/gmod-vibe-coding
npx gmod-vibe-coding-init            # 交互式：项目名 + 平台

# 叠加到已有项目（不覆盖已有文件）：
# cd existing-project
# npm install --save-dev @misakiwww/gmod-vibe-coding
# npx gmod-vibe-coding-init          # --force 覆盖已有文件

AI agent 的部署协议（结构化消费）见部署指南；人类安装与部署步骤见本 README 上文。

工作流

flowchart TD
    Start([需求]) --> Clarify[主会话：澄清需求]
    Clarify --> Create[task.py create]
    Create --> BS[trellis-brainstorm：访谈，逐项确认未决问题]
    BS --> Complex{复杂任务?}
    Complex -->|是| WF[trellis-wireframe：机制 / 界面 / 状态流草图]
    WF --> RS[trellis-research：代码与文档调研]
    Complex -->|否| RS
    RS --> Plan[/prd + design + implement/]
    Plan --> RV[trellis-review：审阅计划]
    RV -->|REVISE| BS
    RV -->|APPROVE| Go[task.py start]
    Go --> IM[trellis-implement：按 implement 清单实现 + 自动提交]
    IM --> CK[trellis-check：质量检查 + 自修]
    CK -->|有问题| IM
    CK -->|通过| Verify[验证：测试矩阵]
    Verify --> SW[trellis-spec-wiki-writer：更新 spec 与 wiki]
    SW --> CD[commit-drafter：整理提交]
    CD --> Done[task.py complete / archive]
    Done --> End([交付])

Phase 1 — Plan

把需求转为可实施的计划。未决问题逐项确认，关键决策有据可查。

| 步骤 | agent | 输入 | 产物 | |------|-------|------|------| | 澄清需求 | 主会话 | 用户需求 | 创建任务 | | 需求访谈 | trellis-brainstorm | prd 模板 | prd.md（未决问题逐项确认） | | 草图 | trellis-wireframe | 复杂机制 / 界面 / 状态流 | 流程图 / 文本草图 | | 调研 | trellis-research | 代码与文档中的未决点 | research/*.md | | 审阅 | trellis-review | 规划产物 | review.md（APPROVE / REVISE） |

产物：prd.md（简单任务）；prd.md + design.md + implement.md（复杂任务）。task.py start 前需通过 trellis-review。

Phase 2 — Execute

按 implement.md 实现，自动提交并留痕，检查至通过。

| 步骤 | agent | 产物 | |------|-------|------| | 实现 | trellis-implement | 代码 + 自动提交（含查证记录） | | 检查 | trellis-check | 问题清单 + 自修 |

检查发现问题则回到实现，修改至通过后进入 Phase 3。

Phase 2.5 — 测试（GMod profile 扩展）

GMod profile 在通用 Trellis workflow 的 Phase 2（Execute）与 Phase 3（Finish）之间插入 Phase 2.5 测试：五层验证矩阵。定义见 profiles/gmod/spec/guides/gmod-workflow.md，层级与工具见 testing-layers.md，probe 编排与决策树见 testing-guide.md。

| 层 | 子层 / 工具 | 阻塞级 | |----|------------|--------| | L1 静态+模拟 | L1a LuaLS / L1b Rust 引擎 / L1c 纯函数 / L1d lint | L1b high + L1d E 级硬阻塞，其余软引导 | | L2 隔离运行时 | GLuaTest（本机 <local_srcds>） | 硬阻塞（FAIL=真 bug） | | L3 生产 | probe_orchestrator.py + <testserver> | 硬阻塞 | | U轨（可选） | 声明式 UI 框架几何 probe | 硬阻塞（同 C 轨） |

L1 自动编排：GMod 项目里 trellis-check 检测到 tools/l1_check.py + .luarc.json 时自动跑 python tools/l1_check.py（git diff 扫 .lua，统一分发 L1a LuaLS / L1b Rust sim / L1d lint，缺工具 exit 0 + WARN 非阻塞）—— AI 无需手动逐工具调用。该入口由 add:gmod overlay 后注入。

Phase 3 — Finish

验证、归档、提交。

| 步骤 | agent / 动作 | 产物 | |------|-------------|------| | 验证 | 测试矩阵 | 测试结果（L1a LuaLS / L1b Rust 引擎 / L1c 纯函数 / L1d lint / L2 GLuaTest / L3 probe） | | 归档 | trellis-spec-wiki-writer | spec 与 wiki | | 提交 | commit-drafter | 提交计划（区分本次改动与遗留改动） | | 收尾 | task.py complete / archive | 任务归档 |

协作机制

主会话：负责任务分配、结果汇总、与用户交互；自身不承担大段代码实现，以控制上下文占用
agent：各自独立上下文，完成后结果回传主会话
协调技能：trellis-channel（多 agent 通信）、trellis-meta（跨阶段状态与配置同步）、trellis-session-insight（上下文用量监控）

工具箱

命令

| 命令 | 作用 | 用途 | |------|------|------| | npx gmod-vibe-coding-init | 叠加协作骨架 | 安装到新项目或已有项目 | | add:gitnexus | 安装 GitNexus 与 MCP 配置 | 启用代码图谱查询 | | add:gmod | 叠加 GMod profile | GMod 项目 | | add:smart-search | 安装 smart-search | 多源网络检索 | | add:assay | 安装 assay | 证据与决策管理 | | sync:vendor | 从 fork 更新 GitNexus dist | 维护 | | sync:tools | 从源仓库更新 GMod 工具 | 维护 |

叠加项目中，add:* / sync:* 从 node_modules/@misakiwww/gmod-vibe-coding/scripts/ 调用（AI agent 的调用决策见部署指南）。

agents（9）

trellis-brainstorm · trellis-wireframe · trellis-research · trellis-review · trellis-implement · trellis-check · trellis-spec-wiki-writer · commit-drafter · gmod-explore

skills（基础 15；另 6 个 `gitnexus-*` 随 `add:gitnexus` overlay，见下文「代码理解」段）

流程：trellis-before-dev · trellis-break-loop · trellis-channel · trellis-meta · trellis-session-insight

文档：trellis-spec-bootstrap · trellis-update-spec · wiki-ingest · wiki-query · wiki-lint · wiki-sync

检查：trellis-check

GMod：gmod-evidence-research

其他：grill-me

治理工具（tools/）

分支与更新日志：branch-doctor.py、changelog_gen.py
harness 管理：harness_health*.py、harness_sync.py、harness_lifecycle.py、claude_harness_audit.py
工作区事务：trellis_workspace/（提交、归档、分支操作的原子化）
GMod（随 add:gmod overlay 落到 tools/，base 不含）：glua_test/（L1b Rust 引擎，Windows 预编译 bin/glua_test.exe，Linux/mac 霭 cargo build --release）、probe_orchestrator.py + console_probe_summary.py + mcp_ssh/（无头服务端 probe，参数化无硬编码路径）、server-sync/、hotreload/、lua_contract_lint.py、luals_check.py、bsp_*、mapport*、full_repack.py

Dedicated Server 声明：server-sync / hotreload / probe 三件涉及 GMod 专用服务器（srcds）的远程 SSH/RCON/热更新操作，需用户单独批准后运行（dist 默认不启用，仅在 add:gmod + 显式配置 policy 后才接入）。

hooks 接入：Claude 平台 hooks 由 init.mjs overlay 自动写入 .claude/settings.json；Codex 平台 hooks 由 overlay 写入 .codex/hooks.json（项目级，需首次 trust）。双平台均新增 gitnexus-guard（PreToolUse）：GitNexus 可用时硬拦 grep/rg/find 搜源码，逼模型用 gitnexus query/context/impact/trace；ALLOW_GREP=1 逃生（搜 log/config 等非索引文本）。详见 installation.md § Platform parity。

代码理解（GitNexus）

add:gitnexus 后，AI 通过代码图谱查询，不依赖关键字搜索：

context({name})：符号的调用方与被调用方
impact({target, direction})：改动影响范围（upstream 谁依赖 / downstream 依赖谁），高风险标注
query({search})：按执行流检索
trace({from, to})：调用路径
rename({symbol, new_name})：基于图谱的重命名（区别于文本替换）
detect_changes()：提交前分析改动影响的执行流

GMod 项目（add:gmod）追加 gmod_scope / gmod_routes / gmod_metatype，区分同名方法在不同元表（Panel / SWEP / ENT）的含义。

装后 .claude/skills/gitnexus-*/ 提供 MCP 用法指南（exploring / impact-analysis / debugging / refactoring / guide / cli），AI 据此选择合适工具与工作流。

详见 docs/gitnexus.md。

定制与维护

定制：docs/customization.md
维护：docs/maintenance.md
同步 vendored 副本：docs/sync.md
GMod profile：docs/gmod-profile.md
证据研究：docs/evidence-stack.md

License

MIT