f-stack-dev-rule

# F-Stack 开发强制规约 本技能是 /data/workspace/f-stack 工作区所有开发任务的强制规约合集，违反任何一条都会导致任务被打回修正，零容忍。 ## 1. Shell 操作脚本规约 严禁直接调用 rm / kill / chmod 系列命令，必须一律通过本 skill 附带的以下脚本执行（位于本 skill 目录的 `scripts/` 子目录，以 SKILL 加载时注入的 base directory 为根拼接绝对路径调用）： ### 1.1 删除文件 → scripts/rm_tmp_file.sh - 单文件：`scripts/rm_tmp_file.sh /full/path/to/file` - 多文件：`scripts/rm_tmp_file.sh /path/a /path/b` - 目录：`scripts/rm_tmp_file.sh /full/path/to/dir` - 回收站位置：`/tmp/.trash`（自动保留路径前缀便于回查） - 永久清理：`scripts/rm_tmp_file.sh --purge <trash_path> [--older-than Nd] [--dry-run]`（purge 白名单仅 /tmp/.trash、/data/.Trash-0/files、/data/.Trash-0/info） - 禁止：直接 `rm`、`rm -rf`、`find -delete`、嵌入 bash 片段 - 批量删除 *.o 等：先用 `ls`/`find` 收集绝对路径再一次性传给脚本 ### 1.2 停止进程 → scripts/kill_process.sh - 单 PID：`scripts/kill_process.sh <pid>` - 多 PID：`scripts/kill_process.sh <pid1> <pid2>` - 禁止：`kill`、`pkill`、`killall`、`kill -9`、`pgrep | xargs kill`、trap/cleanup 内嵌 kill 等任何形式 ### 1.3 修改权限 → scripts/chmod_modify.sh - 用法：`scripts/chmod_modify.sh <mode> <path1> <path2> ...`（mode 与 chmod(1) 兼容，八进制/符号式均可） - 禁止：直接 `chmod`、`chmod -R`、`install -m`、`setfacl` 等任何形式 - 说明：脚本会先快照变更前权限到 /tmp/.trash/、审计到 /tmp/.chmod_audit.log、拒绝高危路径、对 setuid/setgid 位 WARN ### 1.4 通用规则 - make clean / make install 等构建系统 target 属于构建工具操作，允许直接执行 - 若脚本缺少所需功能（如 --reference=），先扩展脚本再调用，不允许临时绕过 ## 2. 编译规约 - 修改任何 .c/.h 后，必须先 `make clean`（或等效完整清理 target）再完整编译，严禁依赖增量编译 - 头文件改动会影响所有 include 它的编译单元，即使只改一个文件也必须 clean - 编译验证以 clean build 通过为准；增量编译通过不作为依据 - 修改公共头文件后，逐一验证所有 include 它的文件可编译；PR 前必须完整 make 无 error - 本机编译环境两个已知坑及规避方式： - IDE 注入 safe-delete hook 会拦截 make clean 内嵌的 rm：用 `PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/root/bin" make clean` 规避 - `make -j16` 与 machine_includes 存在并行竞态：先 `make machine_includes` 再 `make -j16` - 编译基线参考：lib error 0 / warning 51（既有 baseline，新改动不允许新增 warning） ## 3. config.ini 规约 - config.ini 及类似入库配置文件，提交时只允许提交与当前功能特性直接相关的改动 - 严禁提交本地测试/调试环境临时改动：lcore_mask、vlan_filter、idle_sleep、[portN] 本机真实 IP、性能调优临时值等 - 每次 `git add config.ini` 之前必须先 review `git diff` 逐项确认 - 严禁用 `git checkout config.ini` 还原本地测试值（本地配置是运行所必需的，必须保留） - 正确做法：git add 时不选中 config.ini，让本地测试值自然留在未暂存区 ## 4. 文档真实 IP 规约 - 严禁在任何文档（docs、README、spec、测试报告、执行日志、commit message、PR 评论等）中记录本地运行时环境的真实 IP - 必须使用描述性占位符：`<DPDK_NIC_IP>`、`<DPDK_NIC_IPV6>`、`<KERNEL_NIC_IP>`、`<CLIENT_IP>`、`<CLIENT_IPV6>`、`<GATEWAY_IP>`、`<GATEWAY_IPV6>`、`<BROADCAST_IP>`、`<NETWORK_PREFIX>`、`<VIP_IPV6>`、`<BACKEND_IPV6>` 等 - 泛指写法（如 9.134.x）允许，完整真实地址禁止 - `127.0.0.1`、`fe80::` link-local 可写 ## 5. 提交规约 - commit message 一律英文，1-3 句话简单总结，不长篇大论 - config.ini 本地测试值不入库（见第 3 节） - 误提交修复采用 forward-fix（新提交回滚），不改写历史 ## 6. 代码注释语言规约 - F-Stack 工程（/data/workspace/f-stack，含 lib/、freebsd/、example/、tests/ 等所有代码文件）：注释和 git 提交信息都必须使用简短的英文，禁止中文 - 文档类（docs/*.md、spec 中文文档）不受此限，按文档语言要求撰写 ## 7. lib 最小注释规约 - 仅确有必要处写注释：对外接口契约（如 ff_api.h）、配置项含义（如 config.ini）、确实复杂不直观的算法/边界处理 - 严禁给一看就懂的代码加注释（简单赋值、显而易见的分支、自解释调用） - 复杂逻辑的注释也要精炼，优先用清晰命名让代码自解释 ## 8. 多 agent 协作规约 适用于 harness 工程 + 多 agent（agent team / spec 驱动）任务： - **leader 严禁提前退出**：任一子 agent 未回报最终结果前不得结束任务，必须主动轮询等待 - **子 agent 超时探测**：禁止无超时死等；旁路探测（读落盘文件、git 状态、产物路径）优先于消息探测 - **写审分离铁律**：写代码/文档 与 审核 必须不同 agent；leader 严禁自写自审；纯调研/探测/汇总等单一角色可由 leader 兼任 - **bounce≤3**：任一阶段门禁失败必须打回上一步修复，不得带病放行；同一单步骤打回超 3 次立即停止转人工决策 - **异常回退**：子 agent 超时/卡死/与裁决冲突时，可 leader 接管或 spawn 新 agent 重做，但不得违反写审分离 ## 9. 实事求是规约 - 所有行动必须实际执行，严禁未执行就猜测给结果 - 代码/文档/外部数据源交叉验证，不一致处以实际代码为准 - 无法静态坐实或环境不满足的项，如实标注「未坐实/未执行」，不得臆断 PASS ## 10. 资料搜索规约 - 所有提问、分析、调研类任务，必须使用 **f-stack-info-search** 技能来搜索资料 - 覆盖范围：issue 分析、bug 定位、功能调研、方案设计前的资料搜集、技术问题答疑等一切需要查资料的场景 - 搜索流程按 f-stack-info-search 的五部分执行：项目架构文档与知识图谱 → 代码提交记录 → 关联 issue/PR → 公开资料 → 内外网技术网站/博客/公众号等 - 交叉验证：内部文档 + 外部资料 + 实际代码/实测三方证据收敛，不一致处以实际代码为准 - 严禁不搜索资料直接凭猜测回答或给出结论 ## 11. 运行时测试环境 - 本机双网卡：DPDK 独占网卡与 eth1 是不同卡 - 测试 DPDK 网卡程序：通过 `ssh f-stack-client` 从对端机器访问本机 DPDK 接管网卡（IP 用 `<DPDK_NIC_IP>` 占位符） - 本机内核栈测试：用 127.0.0.1 的 lo - 停进程走 kill_process.sh，临时文件清理走 rm_tmp_file.sh，config.ini 临时测试值测完还原且不入库 ## 12. 任务规模判断与 harness 流程规约 - 由提示词或大模型自动判断任务规模：小任务可以直接分析执行；大任务必须按以下步骤进行： - 12.1 功能调研：先使用多 agent harness 方式完成功能调研，产出中文 spec 文档（可安装使用其他 spec 相关 skill）+ 门禁审核；中文文档存放目录 `docs/<FEATURE_NAME>_spec/zh_cn/`；**暂不生成英文 spec 文档**（功能验收完成后再翻译生成英文 spec 文档）；交由人工审核 - 12.2 功能实现与验收：人工审核 spec 文档通过后，由人工提示词触发进入功能实际实现和验收阶段（使用多 agent harness 方式，遵循多 agent 各种相关规则），完成代码编写、CR、测试（单元测试和运行时测试）、文档更新、各里程碑步骤的门禁审核 - 12.3 spec 文档生成和功能实际实现都必须先生成 plan.md 交由人工审核后再执行 - 12.4 按里程碑进行多次 git 提交 - 12.5 测试验收完成后，将 `docs/<FEATURE_NAME>_spec/zh_cn/` 下的中文 spec 文档翻译为英文文档（文件名和文件内容都需要翻译），存放目录 `docs/<FEATURE_NAME>_spec/` ## 13. 测试门禁规约 - 涉及代码改动必须完成单元测试和运行时回归测试 - 单元测试和运行时回归测试同样受门禁规则限制（bounce≤3、写审分离等，见第 8 节）