القائمة
LinCLI 嵌入式 CLI 框架项目开发规范。用于指导在该项目中编写 C 代码、提交更改、管理版本号等开发活动。当 Kimi 在该项目（/home/bunnydeny/programming/LinCLI）中执行代码修改、提交或任何开发任务时触发使用。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| 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