Skip to content

rules.md

Latest commit

 

History

History
594 lines (332 loc) · 21.3 KB

rules.md

File metadata and controls

594 lines (332 loc) · 21.3 KB
Raw

项目协作规范

⚠️ 重要：在开始任何开发工作前，请先完整阅读本文档。本文档定义了本项目的工程规范、协作约定和交付标准，所有开发者必须遵守。

一、项目概况

自行阅读项目 README 了解项目背景和技术栈。

二、多人协作约定

本项目是一个多开发者并行协作的项目。多个并行任务从同一基础代码包出发，各自独立开发不同模块，最终由总架构师统一整合。

作为其中一名开发者，你必须遵循以下协作原则：

  1. 你的代码不是孤岛：你修改的文件可能同时被其他开发者修改。保持改动克制，不要格式化整库、不要重构与你任务无关的代码。
  2. 为整合者着想：总架构师不熟悉你的代码细节。你的注释、文档和命名必须让他能在不做逆向工程的情况下理解你的工作。
  3. 诚实记录技术债务：不要隐藏妥协。任何临时方案、未处理的边界条件、硬编码占位值都必须明确标注，避免整合时被当成"已完成"而埋下隐患。

三、代码注释规范（强制性）

所有新增代码必须包含清晰的中文或英文注释：

代码类型 注释要求
核心业务逻辑 解释「为什么这样设计」，而不仅是「做了什么」
复杂算法 / 数据处理 输入输出说明、边界条件、复杂度考虑
API / 接口方法 功能说明、入参说明、返回值结构、可能抛出的异常
跨模块调用 被调用方的预期行为、调用方的前置条件
临时方案 / 占位代码 必须用 TODO({任务编号}): 原因 标记，说明为什么暂缓、计划何时修复
外部依赖 / 集成点 依赖的版本、配置方式、已知限制

TODO 规范：

  • 任何临时方案、待优化点、未处理的边界条件，必须用 TODO({任务编号}): 原因 标记
  • 示例：TODO(任务1): SSL证书未配置，正式上线前需启用 HTTPS
  • 示例：TODO(任务2): 当前无重试机制，网络不稳定时可能丢请求

四、交付物要求

完成开发后，你的产物必须包含以下文件：

4.1 TASK_LOG.md（执行日志）

路径：docs/T{任务编号}_TASK_LOG.md（放在 docs/ 子目录下）

按时间顺序记录你的全部思考和执行过程：

  • 任务理解：用自己的话复述需求，识别关键验收点
  • 执行计划：分几步做，每步目标和预期产出
  • 详细过程记录：读了哪个文件、改了什么、为什么这样改、遇到的问题和解决方式
  • 产物清单：新增/修改/删除的文件列表（含改动行数估算）
  • 自检报告：对照验收点逐条标注 ✅ 通过 / ❌ 未通过 / ⚠️ 部分通过 / ⛔ 阻塞

4.2 INTEGRATION.md（整合交接文档）

路径：docs/INTEGRATION.md（放在 docs/ 子目录下）

为总架构师撰写的技术交接文档，包含：

a) 完整文件清单

  • 新增的每一个文件的完整路径
  • 修改的每一个已有文件的完整路径 + 改动行数估算
  • 删除的文件（如有）

b) 模块边界说明

  • 你的改动涉及哪些模块
  • 明确指出：哪些文件可能被其他并行任务修改，列出冲突候选文件
    • 已知冲突点（参考其他任务描述）
    • 潜在风险点（你无法确定但怀疑可能冲突的文件）

c) 关键设计决策

  • 你选择了什么技术方案？为什么选它？
  • 有哪些替代方案被你否决了？否决原因是什么？
  • 数据模型/架构的设计考量和权衡

d) 已知技术债务（诚实记录）

  • 哪些地方因为时间/环境限制用了临时方案？
  • 哪些功能标记了 TODO 但未实现？
  • 哪些边界条件你没有处理？
  • 哪些硬编码值（占位 API Key、占位 URL 等）需要在真实部署前替换？

e) 整合注意事项

  • 建议的合并顺序（你的代码应该先合还是后合？为什么？）
  • 与其他任务的冲突解决方案建议
  • 你的改动依赖哪些环境变量、外部服务或配置文件（完整清单）

4.3 截图与测试产物

  • 截图：至少 5 张，覆盖核心功能和关键验收点
    • 命名格式：{任务编号}_{模型代号}_{功能描述}.png
    • 示例：任务1_jetty_AI优化流式输出.png
  • 测试脚本：如有编写自动化测试或验证脚本，全部保留
  • 测试报告：汇总测试结果（通过/失败/阻塞），说明未通过的验收点及原因

4.4 开发阶段记录（创意/设计类任务）

对于涉及 UI 设计、用户体验优化、Logo/动画等创意类任务，必须遵循五阶段开发流程，每个阶段的产出物保存在 docs/ 目录下：

阶段 产出物 路径约定
① PRD / 需求分析 需求文档、功能清单 docs/PRD.md
② 设计图 / 原型 界面设计、信息架构、交互流程 docs/DESIGN.md + 设计截图
③ 技术评估 技术方案选型、可行性分析、风险评估 docs/TECH_REVIEW.md
④ 研发计划 分步实施计划、里程碑、依赖分析 docs/PLAN.md
⑤ 研发实施 实际代码开发 + 上述所有文档 + 截图 代码 + docs/ 目录

五、开发流程要求

  1. 安装依赖：在项目目录下根据项目类型执行 npm install、pip install 或对应包管理器命令
  2. 编译运行：必须自行编译并运行项目，验证产物可用。不能只写代码不运行
  3. 改大文件前备份：修改超过 100 行的文件前，先备份原文件（filename.py.bak）
  4. 修改前先通读：修改任何文件前，先完整阅读该文件，理解现有逻辑
  5. 依赖项记录：新增的外部依赖必须在项目文档中说明用途和版本

六、安全红线

  • API Key、Secret、Token 等敏感信息严禁硬编码在前端/客户端代码中
  • 所有第三方 API 调用必须在服务端/代理端完成（不在客户端直接暴露凭据）
  • 敏感配置通过环境变量或配置文件注入，前端不可见
  • 配置/数据文件中的占位符（如 ***、your-api-key 等）必须替换为实际值或明确标记为待配置
  • 涉及文件操作时检查路径穿越风险（防止 ../../ 等）

七、命名规范

文件类型 命名格式 示例
截图 {任务编号}_{模型代号}_{功能描述}.png 任务1_jetty_AI优化流式输出.png
执行日志 docs/T{任务编号}_TASK_LOG.md docs/T1_TASK_LOG.md
交接文档 docs/INTEGRATION.md —
测试报告 docs/test/report.md —
备份文件 {原文件名}.bak launcher_flet.py.bak

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【三阶段交付指令】诚实自查 → 阶梯达标 → 架构级自审

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

你在执行任务之前和之后，必须严格遵守以下流程。

所有产出物必须保存为实体文件，存放在 docs/review/ 目录下。

该目录就是你本次任务的全部文档仓库。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

第零步：创建文档仓库

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

在项目根目录下（或产物根目录下）创建：

docs/review/
├── 00_GAP_LIST.md          ← 阶段一：差距清单（后变为修复追踪表）
├── 01_SELF_CHECK.md        ← 阶段一：诚实声明与完成度评估
├── 02_80_ACHIEVED.md       ← 阶段二：80分回顾节点记录
├── 03_90_CONFIRMATION.md   ← 阶段二：90分自我确认书
├── 04_ARCH_REVIEW.md       ← 阶段三：架构审查报告（四层面）
├── 05_FIX_LOG.md           ← 修复日志（逐条记录修复过程）
└── INDEX.md                ← 文档索引（自动生成，汇总所有文档的关键结论）

这些文档不是只给评审看的——它们的首要读者是接下来的你自己。

每完成一个阶段，对应文档必须已写入磁盘。最终交付时，docs/review/ 目录必须完整存在。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

阶段一：诚实自查与差距清单 → 产出修复指南

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

在动手修改任何代码之前，先做以下事。

【1.1 理解初始目标】

通读任务描述，明确每一条要求、每个验收点。

把任务目标用你自己的话重述一遍，写入 INDEX.md。

【1.2 自查完成度】

对照每一项目标，逐项检查当前代码/文档/测试的现状。

检查方式必须包含（缺一不可）：

  • 读源码确认功能是否存在，不能只看目录名
  • 运行测试命令确认测试是否能通过
  • 确认测试用例是否存在（不是数文件数，是看测试内容是否覆盖验收点）
  • 确认文档是否存在且内容与当前代码一致

【1.3 产出差距清单 → 这就是你接下来的修复指南】

创建一个文件 00_GAP_LIST.md，这就是你的施工蓝图。

格式要求：

# 差距清单与修复计划

| 编号 | 目标项 | 当前状态 | 差距描述 | 差距等级 | 修复方案简述 | 状态 |
|------|--------|---------|---------|---------|------------|------|
| GAP-001 | 配置持久化保存功能 | 代码不存在 | 未实现任何保存逻辑 | P0 缺失 | 新增 saveConfig()... | ⬜ 待修复 |
| GAP-002 | 配置持久化单元测试 | 测试文件存在但仅1个case | 覆盖不足，缺异常场景 | P1 不足 | 补充边界值测试... | ⬜ 待修复 |
| GAP-003 | Shell工具安全逃逸防护 | 有基础校验但未覆盖所有路径 | 输入过滤不完整 | P1 不足 | 增加白名单校验... | ⬜ 待修复 |

差距等级定义：

  • P0 缺失 = 功能完全没做 / 代码不存在 / 核心路径走不通
  • P1 不足 = 功能做了但不完整 / 边界情况未处理 / 测试覆盖率低
  • P2 优化 = 功能完整但体验/架构/可维护性有改进空间

状态列标记：⬜ 待修复 → 🔧 修复中 → ✅ 已修复 → ➖ 已关闭（无需修复）

⚠️ 这份清单在阶段二中将持续更新——每修复一项就把 ⬜ 改为 ✅。

它既是「现在缺什么」的诊断书，也是「接下来干什么」的任务看板。

【1.4 诚实声明 → 写入 01_SELF_CHECK.md】

# 诚实声明与完成度评估

## 当前完成度估分
XX/100

## 与目标完成度的主要差距
...

## 之前可能「忽悠」或「过度乐观」的判断
1. ...（之前说过"功能正常"但实际测试发现未覆盖）
2. ...

## 本清单真实性承诺
我承诺本清单真实反映了当前代码的实际状态，没有为了"好看"而隐瞒任何已知差距。

【强制约束】

  • 禁止说"大部分功能已完成"而不给出具体数字和证据
  • 禁止跳过任何验收点
  • 如果发现缺口，必须诚实写出来，不允许用"在迭代中完善"来敷衍
  • 如果测试命令执行失败，必须如实记录失败输出，不能只说"测试通过"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

阶段二：阶梯式达标（80分 → 90分）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

分两个子阶段推进。每修复一项，同步更新 00_GAP_LIST.md 和 05_FIX_LOG.md。

【2a. 先到达标状态（80分）】

按 00_GAP_LIST.md 从 P0 到 P1 逐项修复。每修复一项：

  1. 更新 00_GAP_LIST.md：⬜ → ✅，记录修复摘要
  2. 更新 05_FIX_LOG.md：记录修改的文件、改动摘要、测试结果
  3. 运行对应的测试确认修复不引入回归

80分的定义：

  • 所有 P0 差距已关闭（核心功能可运行）
  • 所有 P1 差距中至少 70% 已关闭
  • 主要用户路径（happy path）可完整走通

【80分回顾节点——强制停一下】

完成 80 分后，停下来。不要直接进入 2b。

你在做什么：创建 02_80_ACHIEVED.md，回答以下三个问题，必须诚实回答，不要自欺欺人：

# 80分回顾

## 问题一：当前所有验收点是否都至少有一个实现？
回答+证据：

## 问题二：哪些地方是"勉强能用但心里没底"的？
回答：

## 问题三：如果今天就要交付，我敢不敢签字？
回答：

回答完这三个问题，确认自己真的到了 80 分，再进入 2b。

【2b. 再到满意状态（90分 = 我自己超级满意）】

在80分基础上，把剩余的 P1 和 P2 差距也处理掉。每修复一项同样更新 00_GAP_LIST.md 和 05_FIX_LOG.md。

90分的定义不是我来定的——是你自己觉得"这已经是我能做到的最佳状态了，我挑不出更多问题了"。

当你觉得已经达到90分时，创建 03_90_CONFIRMATION.md：

# 90分自我确认书

## 自证检查清单
(i) 所有验收点都满足了吗？           ┃ 是/否 ┃ 证据：
(ii) 边缘情况和异常路径都处理了吗？  ┃ 是/否 ┃ 证据：
(iii) 代码有没有明显的坏味道？       ┃ 是/否 ┃ 证据：
(iv) 测试覆盖正常+异常路径吗？       ┃ 是/否 ┃ 证据：
(v) 文档与当前代码同步吗？           ┃ 是/否 ┃ 证据：

如果有任何一个回答"否"，说明还没到90分，继续修。

## 已完成的修复汇总（从 05_FIX_LOG.md 中统计）
- P0 关闭：X 项
- P1 关闭：X 项
- P2 关闭：X 项

## 我确认
当前版本已达到我能力范围内的最佳状态（90分）。
签名：（模型名）
日期：YYYY-MM-DD

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

阶段三：架构级自审（从架构师+产品总监的视角）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

当你自认为已经达到90分满意状态后，不能停。

现在你要换一个身份——不再是执行工程师，而是：

角色A：技术架构师 —— 关注代码结构、扩展性、技术债务

角色B：产品总监 —— 关注用户体验、界面细节、商业价值

创建 04_ARCH_REVIEW.md。

从以下4个层面重新审视你的产出，每发现一个问题就记录一条，每个层面至少写出2条发现（无论正面还是负面）：

【3a. 产品界面层面】

用产品总监的眼光看：

  • 界面是否一致（字体、颜色、间距、对齐是否统一）？
  • 是否有不合理的布局、冗余信息、缺失的指引文案？
  • 加载态、空状态、错误状态是否都有对应界面？
  • 中英文混杂、术语不一致的地方？
  • 如果是无界面的 CLI 工具：输出格式是否整齐、帮助信息是否完整、错误提示是否可理解？

【3b. 用户交互层面】

用产品总监的眼光看：

  • 用户操作的反馈是否即时、清晰？
  • 默认值是否合理？用户需要配置的参数是否最少化？
  • 用户犯错时有保护机制吗？（确认对话框、可撤销、自动备份）
  • 无障碍考虑了吗？

【3c. 技术架构层面】

用架构师的眼光看：

  • 模块间的依赖关系是否合理？有没有循环依赖？
  • 配置是否可配置化？硬编码值是否抽离？
  • 错误处理是统一的还是散落在各处？
  • 是否考虑了并发/重入/幂等？
  • 新代码是否符合项目已有的设计模式和编码规范？
  • 是否引入了不必要的依赖？

【3d. 后续可扩展层面】

用架构师的眼光看：

  • 如果需求翻倍（10倍用户、10倍数据量），当前设计能否支撑？
  • 新增一个同类功能需要改多少个文件？能否做到只加文件不改旧文件？
  • 当前的接口/API是否考虑向后兼容？
  • 是否留有扩展点（插件、Hook、配置项）？
  • 如果另一个工程师来接手的代码，他需要多长时间能上手？

【3e. 完整的架构审查报告格式】

# 架构审查报告

## 产品界面层面（总监视角）
| # | 发现 | 类型（问题/亮点） | 建议/已处理 |
|---|------|-----------------|-----------|
| 1 | ... | 问题 | ... |

评分：X/10

## 用户交互层面（总监视角）
...

## 技术架构层面（架构师视角）
...

## 后续可扩展层面（架构师视角）
...

## 最终评分
- 产品界面：X/10
- 用户交互：X/10
- 技术架构：X/10
- 可扩展性：X/10
- 综合评分：X/10

## 签字
架构师：（模型名）
产品总监：（模型名）
日期：YYYY-MM-DD

【3f. 更新 INDEX.md】

最后，更新 docs/review/INDEX.md，汇总所有文档的关键结论：

# 文档索引

## 文档清单
| 文档 | 核心结论 | 最后更新 |
|------|---------|---------|
| 00_GAP_LIST.md | 初始差距 N 项，已修复 M 项 | ... |
| 01_SELF_CHECK.md | 完成度评估：XX/100 | ... |
| 02_80_ACHIEVED.md | 80分回顾结论 | ... |
| 03_90_CONFIRMATION.md | 90分确认结果 | ... |
| 04_ARCH_REVIEW.md | 综合评分：X/10 | ... |
| 05_FIX_LOG.md | 累计修复 N 项 | ... |

## 整体结论
任务整体完成度评估：
待办事项摘要：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

修复日志规范（05_FIX_LOG.md）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

在阶段二中，每修复一项差距，都在 05_FIX_LOG.md 中追加一条记录。

## GAP-001：配置持久化保存功能
- 状态：✅ 已修复
- 修复文件：src/main/config-store.ts（第42-56行新增 saveConfig 函数）
- 改动摘要：增加了配置保存到磁盘的逻辑，绑定到保存按钮事件
- 测试结果：npm test src/main/config-store.test.ts → PASS
- 修复时间：YYYY-MM-DD HH:MM

修复日志的目的是让任何后来者（包括你自己回头看时）能理解每一步改了什么、为什么改、测试是否通过。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

最终交付物清单（必须全部存在）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

docs/review/
├── 00_GAP_LIST.md          ← 差距清单→修复追踪表（状态栏标记进度）
├── 01_SELF_CHECK.md        ← 诚实声明与完成度评估
├── 02_80_ACHIEVED.md       ← 80分回顾节点记录
├── 03_90_CONFIRMATION.md   ← 90分自我确认书
├── 04_ARCH_REVIEW.md       ← 架构审查报告（四层面+评分+签字）
├── 05_FIX_LOG.md           ← 修复日志（逐条记录修复过程）
└── INDEX.md                ← 文档索引与整体结论

检查方式：ls -la docs/review/ 确认7个文件全部存在。

如果缺少任何一个，整个交付被视为不完整。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

模型自省红线

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  1. 诚实不是选择——差距清单中漏掉任何一项你知道但没写的缺口，比写出来更扣分。
  2. "我能力范围内"不是借口——如果你觉得某个验收点自己做不到，必须明确写出来并在 GAP_LIST 中提供替代方案建议。
  3. 90分的定义权在你，但证据也在你——我不需要你告诉我"我达到了"，我需要你展示你达到了的证据（测试输出、文件内容、运行截图）。
  4. 架构审查不是为了刁难你——是为了让你自己发现自己还能做更好。即使90分的代码，在架构师眼里也一定有改进空间。
  5. 不要跳过阶段直接给最终结果——三阶段依次执行，每个阶段的文档产物都必须保存到磁盘。
  6. docs/review/ 是你的工作底稿——它记录了你从"发现差距"到"修复完成"到"架构审查"的全过程，不是给别人看的装饰品，是你自己施工时的参照物。