Your Name
cdd0be328a
Critical runtime bugs:
- terminal.html WebSSH完全不可用（URL前缀/JSON解析/Content-Type三处错误）
- servers.py路由遮蔽：/logs被/{id}拦截，3个前端页面同步日志查询失败
- scripts.html startExecPoll()→startExecPolling()，长任务快速执行崩溃
- agent.py {value!r!s:.50}格式串非法，agent发非数值时ValueError
- alerts.html d.daily.reduce()无null检查，API返回空数据时TypeError
Resource leak / stability:
- websocket.py僵尸连接未关闭TCP，文件描述符泄漏
- websocket.py _last_alert_time字典无限增长（加1小时过期清理）
- asyncssh_pool.py全忙时超过MAX_CONNECTIONS无限增长
- self_monitor.py Telegram告警无冷却，宕机时每30秒刷屏
- schedule_runner.py一次性调度执行超60秒会重复触发
- 限速脚本EXPIRE每次重置窗口可绕过（改用Lua原子脚本）
Security:
- JWT access token加token_version声明，改密码后旧token立失效（零宽限）
- INSTALL_MODE导入时常量→动态函数，安装后JWT认证不再残留禁用
- install.py /lock端点加管理员存在性验证，防止阻断安装
- ServerUpdate schema移除connectivity只读字段，防止伪造连接状态
Frontend fixes:
- doExec()缺r.ok检查、commands.html null检查
- _server_to_dict()补last_checked_at+ssh_key_public
- _field_match()逗号cron表达式修复
- alerts类型显示、SSH会话名称、搜索高亮定位
- 一次性/循环定时任务（run_mode+fire_at+自动禁用）
Dead code removed (400+ lines):
- SyncService batch_push/_push_single等5个方法（零调用者）
- 5个未使用schema（SyncCommands/SyncConfig/SyncSftp/FileDeploy/PaginatedResponse）
- 6个零调用service方法、3个无前端API端点
- 4个未使用import
Schema migrations:
- push_schedules: run_mode + fire_at列，cron_expr改NULL
- servers: 7个新列 + ssh_key_private/public VARCHAR(500)→TEXT
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
63 lines
2.6 KiB
Plaintext
63 lines
2.6 KiB
Plaintext
---
|
|
description: 完美实现原则 — 禁止降级/妥协/技术债；设计文档与技术文档先行；每次修改写 changelog
|
|
alwaysApply: true
|
|
---
|
|
|
|
# 完美实现与文档纪律
|
|
|
|
## 实现标准（强制）
|
|
|
|
**所有设计和实现都必须是完美实现。**
|
|
|
|
- ❌ **不允许为了实现而实现** — 每一行代码、每一个接口必须有明确目的，达到项目既定的安全、架构与质量标准
|
|
- ❌ **不允许降级实现** — 不得以「先用着」「以后再改」为由降低安全、性能、可维护性或用户体验
|
|
- ❌ **不允许妥协实现** — 发现问题必须根治，不得用绕过、静默吞错、硬编码掩盖代替修复
|
|
- ❌ **不允许留技术债** — 不得留下 TODO/FIXME/「临时方案」延后处理；当场能修必须当场修
|
|
- ✅ **无法完美实现时必须停下** — 与用户沟通并确认替代方案后，才能换方案；不得擅自从权或自行降级
|
|
|
|
## 文档纪律（强制）
|
|
|
|
### 设计文档
|
|
|
|
- 所有**新功能、架构变更、非平凡重构**必须先有设计文档，再写代码
|
|
- 设计文档路径：`docs/design/specs/YYYY-MM-DD-<topic>-design.md`
|
|
- 设计文档至少包含：背景与目标、方案对比、选定方案及理由、接口/数据模型、安全与性能约束、验收标准
|
|
|
|
### 技术文档（开发前）
|
|
|
|
- 开发前输出技术文档（实施说明），路径：`docs/design/plans/YYYY-MM-DD-<topic>.md` 或 `docs/reports/<step>/engineering-report.md`
|
|
- 技术文档至少包含：涉及文件清单、实现步骤、依赖与配置变更、测试要点、回滚方式
|
|
- 项目里**已有模块但缺文档的，在改动时一并补全**，不得只改代码不留档
|
|
|
|
### Changelog（每次修改）
|
|
|
|
- **每一次**有意义的代码或配置修改，必须在 `docs/changelog/` 新增或更新记录
|
|
- 命名：`YYYY-MM-DD-<简短主题>.md`
|
|
- 每条记录至少包含：日期、变更摘要、动机、涉及文件、是否需迁移/重启、验证方式
|
|
- 禁止把 changelog 写在 commit message 里代替项目文档
|
|
|
|
## 执行顺序
|
|
|
|
```
|
|
需求确认 → 设计文档 → 技术文档 → 实现 → 测试验证 → changelog →（必要时）更新 CLAUDE.md/AGENTS.md
|
|
```
|
|
|
|
## 禁止示例
|
|
|
|
```python
|
|
# ❌ 技术债
|
|
# TODO: fix later
|
|
pass # workaround
|
|
|
|
# ❌ 降级
|
|
except Exception:
|
|
return None # 静默失败
|
|
|
|
# ❌ 无文档直接大改
|
|
# （新增整模块却无任何 docs/design 或 docs/changelog 记录）
|
|
```
|
|
|
|
## 允许的唯一例外
|
|
|
|
经用户**明确书面确认**后，方可采用非完美方案；须在 changelog 中记录例外原因、影响范围与后续补齐计划。
|