# vlang-skill

**Repository Path**: iqdo/vlang-skill

## Basic Information

- **Project Name**: vlang-skill
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-14
- **Last Updated**: 2026-07-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# v-fullstack-dev 使用说明

V 0.5.2 全栈开发技能的**单一真源**（编译器位于 `~/v`，版本 0.5.2 / b07c40e）。
本技能是 V 语言相关开发的统一入口，合并了原先分散在多处、层级不一、易产生矛盾的
多个技能（v-lang-05x-patterns、vlang-fullstack/medium-project、v-sqlite-orm-pitfalls、
v-openai-compatible-llm-wirefmt、v-go2v-port、go-to-v-porting、v-gui、vlang-web-dev）。

## 何时会被加载
当任务涉及以下任意一项时，Agent会自动加载本技能（或你手动要求）：
- V 语言 / veb / V CLI / V 数据库 / V 模块 / V 测试 / V 构建
- V 终端程序（term / term.ui）或 V GUI（ui / gui）
- 项目根目录存在 `v.mod`
- V 编译报错、或调用 OpenAI 兼容 LLM 返回 HTTP 400、或 Go→V 移植任务

## 目录结构
```
v-fullstack-dev/
├── SKILL.md              # 主文件（≤10KB）：最高频坑位 + 路由索引 + 工作流
├── readme.md             # 本说明
├── references/           # 各主题深度参考（每个 ≤10KB）
│   ├── *.md              # 主题参考
│   ├── *_pt2.md          # 同一主题的续篇（原文件超 10KB 拆分而成）
│   ├── xp_*.md           # 已验证的项目级实战配方（worldbank / veb / ORM store 等）
│   ├── ci_template.yml / classify_modules.sh / known_good_patterns.v
│   └── ARCHIVED.md       # 被合并的旧技能索引与去向
├── templates/            # 1BRC C-FFI 性能参考代码（.v）
└── scripts/              # validate_tr.py（.tr 翻译文件校验）等
```

## 如何使用
1. **先读 `SKILL.md`**：它汇总了每个主题的最高频坑位 + 一句话正确写法，多数日常问题在此解决。
2. **按需读取 `references/`**：`SKILL.md` 每个小节末尾都标注了 `detail: references/xxx.md`，遇到具体领域再打开对应文件看完整配方与代码。
3. **拆分续篇**：带 `_pt2` 后缀的文件是同一主题的后续部分（如 `c_ffi_pt2.md` 是 `c_ffi.md` 的高性能 1BRC 配方），遇到截断处继续读 `_pt2` 即可。
4. **项目级配方**（`xp_*`）：是某个真实项目（vaiv / worldbank / covonaut 等）里验证过的写法，能直接套用或改写。

## 参考文件索引（按主题）
| 主题 | 主参考 | 续篇 / 补充 |
|------|--------|-------------|
| 语法 / 运行时坑 | `syntax.md` | `xp_*` 实战配方 |
| veb 路由 / 模板 / 静态 | `web_veb.md` | `xp_veb_*.md` |
| db.sqlite ORM | `db_orm.md` | `db_orm_deep.md`(+`_pt2`)、`xp_sqlite_orm_store.md` |
| JSON / HTTP / i18n | `json_http.md` + `i18n_json2.md` | `xp_worldbank_json.md` |
| 并发（go/chan/select） | `concurrency.md` | — |
| OpenAI 兼容 LLM 接线 | `openai_llm.md` | `openai_llm_deep.md`(+`_pt2`)、`openai_sse_streaming.md`、`openai_shangtang_verify.md` |
| C FFI（mmap / SIMD） | `c_ffi.md` | `c_ffi_pt2.md` |
| 终端编程 term / term.ui | `tui.md` | `tui_pt2.md` |
| GUI（ui / gui） | `gui.md` | `gui_frameworks.md`(+`_pt2`) |
| Go→V 移植（go2v） | `go2v.md` | `go2v_workflow.md`、`go2v_pitfalls.md`、`classify_modules.sh`、`xp_go2v_*.md`、`known_good_patterns.v` |
| 项目结构 / 构建 / 测试 / vet | `build_test_vet.md` | `ci_template.yml`、`xp_multi_session_cli.md` |
| 1BRC 性能参考 | `1brc_benchmarks.md` | `templates/1brc_*.v`、`scripts/1brc_readme.md` |

> 关于 V 0.5.2 的新变化（已核实）：JSON 用 `import json2`（vlib 正式模块，旧 `x.json2` 仅为别名）；
> 新增 `vlib/i18n` 国际化模块（`load_tr_map` / `tr` / `tr_plural`）。详见 `references/i18n_json2.md`。

## 与原技能的关系
- 本技能合并了上述所有旧技能；旧版原文**未删除**，保留在 `~/.hermes/skills_bak_archive/`
  （用户硬性偏好：保留可恢复，不直接删）。
- 每个旧技能的去向见 `references/ARCHIVED.md`。
- `vlang-coder` profile 的软链 `v-fullstack-dev` 已指向本目录（旧的 `v-lang-05x-patterns`
  冗余软链已移除）。

## 维护约定（重要）
用户硬性要求：**每踩到一个 V 0.5.x 编译期/运行期陷阱（pitfall），都要同时固化为两层资产**——
1. 写入系统级约定 `~/.vaiv/conventions.md`（vaiv 会话自动注入 system 提示）；
2. 补丁到本技能的对应 `references/*.md`（跨会话自动加载）。

修改本技能时请保持：主 `SKILL.md` ≤10KB；`references/` 下每个文件 ≤10KB（超额拆 `_pt2`）。