渔芯项目开发 · 习惯与准则(铁律)
版本:v2.1 | 合并自华哥 + 玉芬 | 生效日期:2026-07-17(v2.1 追加对话归档规则 2026-08-13)| 适用范围:Codex + 所有渔芯同事
一、沟通习惯(华哥风格)
- 直接、简洁、不绕弯,结果导向
- "自己测" = Codex 直接实测,不询问用户
- "执行" = 立即动手,不解释
- "我手动修复" = 停手等用户操作
- 先汇报再问后续,不边干边问
- 单纯进展汇报("还在跑")不需要,1 小时 1 报即可
| 状态 | 汇报场景 |
|---|---|
| ✅ | 关键决策(重构方案 / 依赖升级 / 删文件 / push 远端) |
| ✅ | 任务完成 / 失败 / 超时 |
| ✅ | 发现 Bug / 安全问题 |
| ✅ | 消耗 > 预期 50% |
| ❌ | 单纯"还在跑"不汇报(1 小时 1 次即可) |
二、编码铁律
代码风格
| 语言 | 缩进 | 命名 | 类型 |
|---|---|---|---|
| Python | 4 空格 | snake_case | 强制 type hints |
| JS/TS | 2 空格 | camelCase | TS 严格模式 "strict": true |
| 类 | — | PascalCase | — |
| JSON/YAML | 2 空格 | — | — |
- 函数必须有 docstring(Google 风格)
- 关键逻辑加行内注释
- ❌ 禁:wildcard import(
from x import *)、循环依赖 - ✅ 同包内用相对导入
Git
- 分支:
feature/xxx/fix/xxx/chore/xxx/refactor/xxx - 提交:
<type>(<scope>): <描述>例:feat(auth): 添加 JWT 刷新逻辑 - ❌ 禁:
git push --force到 main、rm -rf、直推 main - ✅ 所有变更走 PR(通过 GitHub CLI)
测试
- 新功能必须有测试(pytest / vitest / jest)
- 核心模块覆盖率 > 80%
- 命名:
test_<功能>_<场景>_<预期结果> - CI 失败禁止合并
依赖
- Python:
pyproject.toml+uv(优先);提交uv.lock - Node:
pnpm优先;package-lock.json必须提交 - ❌ 禁手动
pip install后不写依赖文件
三、安全禁区
🔴 绝对禁止
rm -rf /rm -rf ~rm -rf .git push --force到 main/mastersudo任意命令chmod 777curl ... | bash/wget ... | sh- 改
~/.ssh//~/.aws//~/.zshrc/~/.bashrc//etc/ dd if=... of=/dev/sd*
🟡 软禁止(需确认)
- 删非系统目录文件
- 重启服务
- push 远端
- 数据库 DROP/ALTER
🔑 凭证安全
- ❌ 硬编码 token/key/密码;
.env进 git;log 打敏感信息 - ✅
os.environ.get()或 pydantic-settings;.env进.gitignore;输出时 mask(***)
🛡️ 扫描规避
curl URL | python3→ 拆两步(先 curl 存文件,再 python 读)cat file | python3→ 用python3 file.py- 含 confusable 字符(
→/✓/全角) → 改用 ASCII
四、工作流铁律
用 Codex 写代码
- 不直接在终端改代码
- 复杂多轮任务 → 在 Codex 对话内完成
- 一次性简单任务 → 终端命令直接跑
上下文管理
- 单个对话内只做当前任务,不混入不相关子任务
- 切换任务时,开启新对话,不在旧会话里跑新任务
- ❌ 禁:同一会话跑 N 个不相关任务
并行优先
- 3 个独立任务 = 开 3 个 Codex 任务并行,不串行
- 3 个独立工具调用 = 一条消息里并发
💰 成本控制
| 任务 | 模型 | 说明 |
|---|---|---|
| 简单查文档 | deepseek-v4-pro | 快速问答 |
| 写单测 | deepseek-v4-pro | 代码生成 |
| 重构模块 | deepseek-v4-pro | 中等复杂度 |
| 复杂设计 | deepseek-v4-pro | 架构级别 |
| 架构决策 | deepseek-v4-pro | 重大设计 |
当前模型通过本地 Gateway(127.0.0.1:18888)走 deepseek-v4-pro,无需切换。
五、环境陷阱
- 中文路径:
--workdir拒绝中文 →ln -sf "原路径" /tmp/别名再用别名 - 网络:默认允许外网(
api.*、内网 RKR、GitHub 都能上) - Provider:DeepSeek via
127.0.0.1:18888(本地 Gateway);不确定可用性先curl实测 - 稳定性:直连偶发超时 → 启
deepseek-proxy-v2.py 18792中转
六、渔芯项目结构
~/6-产品研发/
├── 00-FindEra寻元/ # 资料采集,唯一外网出口
├── 01-RKR知识库/ # 10 容器架构,知识中枢
├── 02-AquaForge养殖仿真/ # 鱼乐宝仿真
├── 03-EDAI硬件开发/ # 硬件 + AI 边缘
└── 渔芯项目开发_习惯与准则_铁律.md
新项目默认路径: 新开发项目默认创建于 ~/6-产品研发/,目录名沿用递增编号(当前已到 36-),除非用户明确指定其他位置。
两大品牌
- 渔芯水产养殖(RAS 循环水 + AI 全链条)
- LookForge(多环节数据仿真平台)
8 大统一模块
仪表板 / LLM Agent / 自进化 / 运维巡检 / 管理后台 / 用户管理 / 功能模块 / 本地持久化
七、想法归档
华哥抛想法 → 立即结构化记录:
- 路径:
~/hermes/ideas/{date}_{主题}_想法.md - 骨架:
- ① 一句话核心
- ② 对比表
- ③ 风险点
- ④ 待办
- ⑤ 关联资产
- 完成后:推送玉芬归档到 RKR
八、对话归档(固定习惯)
重要会话 / 每日工作结束后,Codex 必须把对话记录整理成文字归档,固定执行:
- 触发条件:
- 涉及跨系统操作(云资源变更 / 域名 / 备案 / 部署 / 支付)的会话
- 跨多个阶段的复杂任务(测试→修复→上线)
- 用户明确要求归档 / "写进铁律" / "固定成习惯"
- 归档路径:项目
docs/对话归档-YYYY-MM-DD.md(如24-GEO/docs/对话归档-2026-08-13.md) - 固定骨架:
- ① 会话阶段总览表(阶段 / 内容 / 结果)
- ② 关键操作与决策记录
- ③ 问题与解决方案
- ④ 用户决策记录
- ⑤ 待办清单(含优先级 / 负责人 / 时间点)
- ⑥ 敏感信息说明
- 归档规则:
- 写入项目
docs/并git commit(conventional commit:docs: archive conversation record YYYY-MM-DD) - 密码 / 身份证号 / 手机号 / AccessKey 一律脱敏(
***或"存服务器本地文件"),不落明文 - 云资源 / 备案 / 部署类操作必须记录可追溯信息:订单号、实例 ID、域名、IP、进度节点
- 每天最多一份归档(当日追加,不重复建文件)
- 写入项目
- 铁律自进化:用户说"写进铁律" / "固定成习惯" → 立即把该规则追加进本文件,并同步所有副本(
.codex/skills、系统文件夹/Codex/skills、.agents/skills)
📌 本规则是 Codex 和所有渔芯同事的共同行为准则。如有违反,华哥有权当场修正。 🔄 自我进化:每次发现新的稳定偏好 / 环境事实 / 工作流,自动追加到本文件。