Menu
LinCLI 嵌入式 CLI 框架项目开发规范。用于指导在该项目中编写 C 代码、提交更改、管理版本号等开发活动。当 Kimi 在该项目（/home/bunnydeny/programming/LinCLI）中执行代码修改、提交或任何开发任务时触发使用。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | lincli-dev |
| description | LinCLI 嵌入式 CLI 框架项目开发规范。用于指导在该项目中编写 C 代码、提交更改、管理版本号等开发活动。当 Kimi 在该项目（/home/bunnydeny/programming/LinCLI）中执行代码修改、提交或任何开发任务时触发使用。 |
版本号定义在 include/cli_config.h：
#define CLI_VERSION_MAJOR 1
#define CLI_VERSION_MINOR 3
#define CLI_VERSION_PATCH N
任何提交前必须自增 PATCH 字段（N += 1）。dev 是活跃分支，每次提交代表一个补丁，不得遗漏。
先切换到 dev，将版本号升级为发布版本：
git checkout dev
修改 include/cli_config.h：
MINOR += 1PATCH = 0例如从 1.3.15 改为 1.4.0。
然后提交这个版本号改动：
git add include/cli_config.h
git commit -m "chore: 升级版本号至 v1.4.0，准备发布"
git checkout main
git merge --no-ff dev
由于版本号已在 dev 上提前升级，合并时 include/cli_config.h 不会出现冲突。
合并完成后，必须在 merge 结果上执行以下两步：
打 tag：在 merge 完成后的 main 分支上创建版本标签
git tag v$(MAJOR).$(MINOR).0
git push origin v$(MAJOR).$(MINOR).0
例如 v1.4.0。tag 必须打在 merge 之后的 commit 上，不得提前。
编写 release 文档：在 /tmp/ 目录下创建 release-v{MAJOR}.{MINOR}.0.md，汇总该小版本在 dev 分支上的全部变更。
若用户**没有明确说"不要提交"、"只编译不提交"、"暂时不推送"**等，则在编译和测试成功后，默认自动执行 git add、git commit、git push。
⚠️ 此条优先级高于代码阅读与静态分析。
当用户报告终端交互类 bug（如 Tab 补全异常、光标移动错乱、退格后行为异常、候选列表显示错误等）时：
不得在只读代码、脑补状态流之后就动手修改。用户的文字描述通常只能传达现象的七八成，剩余的细微差别往往才是根因所在。
pty、pexpect 或类似工具启动 build/bin/a.out<tab><tab><退格><tab>）本项目是嵌入式 CLI 框架，核心逻辑围绕状态机 + 终端光标控制 + 字符缓冲区展开。静态分析极易被以下细节误导：
prefix_len 正确，但 prefix 指针指向的缓冲区被 do_delete() 回填的空格污染candidate_ctx 某个字段没被 candidate_ctx_clear() 清除，导致后续 Tab 走偏分支display_unified_cmd_list() 的 rows 计算漏掉手动输出的分隔换行cmd_line.buf[size] 位置的脏数据让 strstr() 把前缀误读成带空格的字符串这些 bug 的共同特点是：代码逻辑看起来都对，但运行时缓冲区状态被先前的操作污染了。只有实际跑程序才能暴露这种时序/状态污染问题。
💡 先跑程序看见现象，再读代码定位根因，最后动手修改。 顺序颠倒会导致反复修复、反复出错，浪费双方大量时间。
test_*.py、debug_*.sh 等用于启动 a.out 并捕获 ANSI 输出的 Python/Shell 脚本）.gitignore 中排除git add -A 前务必检查 git status，确认没有误加临时文件所有 Git 提交日志必须使用中文。禁止使用英文提交信息。
栈上临时缓冲区若大于 32 字节，优先改用项目内存池：
char *buf = cli_mpool_alloc();
if (!buf) { /* 处理 OOM */ }
/* 使用 buf */
cli_mpool_free(buf);
cli_mpool_alloc() 必须在同一代码路径内配对 cli_mpool_free()<oom> 并安全返回，禁止继续使用 NULL 指针适用范围：src/cli/、src/init/、tests/ 目录下的源文件。
不适用范围：src/lib/ 目录下的成熟基础库代码（如状态机、红黑树、内存池等），无需为此类代码做行数拆分。
适用范围内的函数不得超过 25 行（物理行数，含空行与注释）。超过时必须拆分为更小的函数。
拆分原则：
如果拆分后无法百分之百确认逻辑未发生变化，必须：
遵循项目根目录 .clang-format 配置。不得引入与其冲突的格式。
在修改代码、添加功能或回答用户问题之前，必须详细阅读以下文档，从用户视角理解框架的功能接口：
docs/architecture.md — 架构与核心机制docs/async_commands.md — 非阻塞命令docs/init.md — 开机初始化docs/porting.md — MCU 移植docs/customization.md — 日志定制docs/cli_var.md — 变量系统docs/candidates.md — Tab 补全候选docs/inline_print.md — 尾行模式docs/tests.md — 测试用例说明tests/commands/ 目录下的每个 .c 文件都是用户接口的完整示例程序：
test_bool.c、test_int.c、test_double.c、test_string.c — 基础选项类型用法test_int_array.c、test_conflicts.c、test_required.c — 高级选项特性test_callback.c、test_with_buf.c — 自定义缓冲区与回调test_auto_cmd.c — 开机自动执行命令test_led.c、test_motor.c — 完整命令示例（含异步命令）test_log.c — 日志过滤测试test_key_interaction.c — 键盘交互测试test_init_d.c — 初始化函数测试test_cli_var.c — 变量系统测试tests/unit/ 目录下是 Unity 单元测试，测试基础库函数（string、atoi、float、mpool、vector、vsnprintf、stateM、errno）。
规则：每份测试代码都展示了用户如何注册命令、定义选项、写 handler。新增功能前必须参考同类测试用例，确保新接口与已有风格一致。
适用范围：项目内所有 .md 文件，包括但不限于 README.md、docs/*.md、release 文档。
章节标题前必须加 emoji
## 快速开始 必须写成 ## 🚀 快速开始）列表项必须加 emoji
- ✅ 功能A、- 🔹 功能B）表格内必须加 emoji
提示/警告/注意块必须加 emoji
💡 或 ✨⚠️ 或 🐛📌 或 📝禁止整篇文档完全没有 emoji
| 场景 | 推荐 Emoji |
|---|---|
| 章节标题（总览/介绍） | 🎯 📋 🌟 |
| 章节标题（功能/特性） | ⚙️ 💡 🔧 🛠️ |
| 章节标题（指南/教程） | 📖 📚 🎓 |
| 章节标题（对比/选型） | ⚖️ 🔍 📊 |
| 功能/特性列表项 | ✅ ❌ 🔹 💎 🆕 |
| 状态/结果 | 🟢 🔴 🟡 ✅ ❌ |
| 步骤/流程 | 1️⃣ 2️⃣ 3️⃣ 或 🥇 🥈 🥉 |
| 提示/建议 | 💡 ✨ 🔔 |
| 警告/注意 | ⚠️ 🐛 🚨 |
| 代码/技术 | 💻 🔌 ⌨️ |
| 性能/体积 | 🪶 ⚡ 📉 📈 |
| 移植/硬件 | 🔌 🔧 🖥️ |
## 🎯 快速开始
### 💡 前置条件
- ✅ 已安装 GCC
- ✅ 已安装 CMake
- ❌ 不需要额外依赖
### ⚙️ 编译步骤
1️⃣ 克隆仓库
2️⃣ 执行 `make menuconfig`
3️⃣ 执行 `make`
> ⚠️ 注意：首次编译会自动生成 `cli_kconfig.h`
## 快速开始
### 前置条件
- 已安装 GCC
- 已安装 CMake
### 编译步骤
1. 克隆仓库
2. 执行 make menuconfig
3. 执行 make
> 注意：首次编译会自动生成 cli_kconfig.h