# 项目主动维护策略

> 通用方法论，适用于任何软件项目的长期健康度维护。
> 具体项目和工具链请根据实际情况替换。

---

## 什么是主动维护？

被动维护 = 等问题爆发再去修，成本高、影响大。

主动维护 = 定期检查、预防性修复、持续沉淀团队知识，成本低、可持续。

---

## 一、维护的四个维度

```
┌─────────────────────────────────────────────────────────┐
│                     主动维护四维度                        │
├─────────────┬─────────────┬─────────────┬────────────────┤
│   文档维护   │   代码质量   │   架构健康   │    发布运营    │
│             │             │             │                │
│ · 版本对齐   │ · 测试覆盖   │ · 边界审计   │ · 冒烟验证    │
│ · wiki审计   │ · 死代码清理 │ · 循环依赖   │ · CHANGELOG  │
│ · 依赖审计   │ · 大文件审计 │ · 性能基线   │ · 发布清单    │
│ · 知识沉淀   │ · 类型覆盖   │ · 安全检查   │ · 回滚预案    │
└─────────────┴─────────────┴─────────────┴────────────────┘
```

---

## 二、文档维护

### 2.1 版本号一致性（每次发布前）

**问题**：文档 header 里的版本号落后于实际版本，用户/Agent 读到过时信息。

**解决方案**：
- 扫描所有 `.md` 文件中的 `Current version: vX.Y.Z` 或 `Last verified: YYYY-MM-DD | Current version: vX.Y.Z` header
- 与当前 git tag 比对，不一致则 CI 失败或警告

**工具示例**（通用伪代码）：

```bash
# 扫描所有 markdown 文件的版本 header
CURRENT_TAG=$(git describe --tags --abbrev=0)

for file in $(find . -name "*.md"); do
  VERSION=$(grep -oP 'Current version: v\K[\d.]+' "$file" | head -1)
  if [[ "$VERSION" != "$CURRENT_TAG" ]]; then
    echo "OUTDATED: $file (doc: $VERSION, current: $CURRENT_TAG)"
  fi
done
```

**维护节奏**：每次发版前执行

### 2.2 Wiki/Docs 审计（定期）

**问题**：文档之间互相矛盾、引用已移除的路径或模块、Out 的信息未被标注。

**审计清单**：
- 文档间是否有冲突描述（同一事实两种说法）
- 是否引用了已被移除的 package/module/文件路径
- 是否有过时的技术选型描述（如 "旧版 XXX 已废弃" 但新方案已上线）
- 表格/列表数字是否一致（Agent 数量、渲染器数量等）
- 文档之间互相引用是否仍然有效

**维护节奏**：每月或每个大版本前

### 2.3 依赖版本审计（定期）

**问题**：`package.json` 中的 `^x.y.z` 版本范围下界是否真的有需要的 API，导致在旧版本环境运行失败。

**审计清单**：
- `package.json` 所有依赖的版本范围下界
- 是否有依赖已经停止维护但仍在使用
- 是否有安全漏洞（CVE）的依赖

**工具**：`npm audit`、`dependabot`、`renovate`

**维护节奏**：每月

### 2.4 知识沉淀（持续）

**问题**：踩过的坑、解决的 bug、重要的架构决策没有记录，新人或新 Agent 重复踩坑。

**解决方案**：
- 建立 `KNOWN_PITFALLS.md` 或项目 wiki 的 `pitfalls/` 目录
- 每个坑记录：问题现象 → 根因 → 解决方案 → 回归测试
- 每次 bugfix 后，问自己"这个坑以后怎么避免"，答案写进去

**维护节奏**：每个 bugfix 后

### 2.5 双语文档一致性（定期）

**问题**：`README.md` 和 `README_zh.md`、中文 skill 和英文 skill 内容不同步。

**审计清单**：
- 结构是否完全一致（同样的章节顺序）
- 数字和名称是否一致
- 翻译是否准确反映原文意图

**维护节奏**：每月

---

## 三、代码质量维护

### 3.1 测试覆盖（持续）

**覆盖率基线**：
- 每次 PR 显示覆盖率 diff，覆盖率下降超过阈值（如 2%）必须审核
- 新功能必须有测试（单元测试 + 集成测试）

**覆盖率目标**（参考值）：
- 核心业务逻辑：>80%
- 工具函数/纯函数：>90%
- UI 组件：按需（交互逻辑需测试）

**维护节奏**：每次 PR + 季度趋势回顾

### 3.2 死代码清理（定期）

**问题**：未使用的 import、变量、函数堆积，导致代码阅读和维护成本增加。

**工具**：
- TypeScript：`typescript-eslint --no-unused-vars`
- 其他语言：各语言对应的 linter
- IDE 检查

**维护节奏**：每月或每个大版本前

### 3.3 大文件/长函数审计（定期）

**问题**：单个文件 >500 行或单个函数 >100 行，维护成本急剧上升。

**解决方案**：
- 设置 CI 门禁：超过阈值警告或失败
- 定期重构：将大文件拆分，将大函数拆小

**维护节奏**：每季度

### 3.4 类型安全（定期）

**问题**：`any` 类型使用过多，TypeScript 形同虚设。

**目标**：逐步将 `any` 替换为具体类型或 `unknown`

**维护节奏**：每季度审计 `any` 使用率，趋势应该是下降

### 3.5 性能基线（定期）

**问题**：性能在不知不觉中劣化（启动变慢、内存泄漏、查询变慢）。

**建立基线**：
- 记录关键指标的初始值（启动时间、搜索延迟、内存占用）
- 每次 PR 可以有性能回归测试

**工具**：` Clinic.js`、`0x`、`heap snapshot` 等

**维护节奏**：每月或每个大版本

---

## 四、架构健康维护

### 4.1 边界审计（每个大版本）

**问题**：模块之间的边界模糊，循环依赖、跨边界违规 import。

**审计清单**：
- 是否有循环依赖（A→B→C→A）
- 是否有跨模块/跨包的违规 import
- 模块职责是否单一（Single Responsibility）
- API 契约是否稳定

**工具**：`madge`（JS）、`dependency-cruiser`、`go mod graph`

**维护节奏**：每个大版本前

### 4.2 安全检查（持续）

**问题**：安全漏洞被引入或未被发现。

**检查清单**：
- 依赖是否有已知 CVE
- 用户输入是否验证和清洗（SQL 注入、XSS、路径遍历）
- 敏感信息（API key、密码）是否硬编码
- 权限检查是否完整

**工具**：`npm audit`、`Snyk`、`OWASP Top 10 checklist`

**维护节奏**：每次 PR + 每月全面扫描

### 4.3 设计系统合规（前端项目，定期）

**问题**：UI 组件不遵守设计规范，颜色/字体/z-index/圆角不一致。

**检查清单**：
- 颜色值是否来自 CSS 变量（禁止硬编码 hex）
- z-index 是否在允许范围内
- 动效时长是否超标（>300ms）
- focus ring 是否使用 `focus-visible:`

**工具**：ESLint 插件 + PR 截图 diff

**维护节奏**：每次前端 PR

---

## 五、发布运营维护

### 5.1 冒烟验证（每次发版后）

**问题**：发版后才发现核心功能不可用。

**验证清单**：
- CLI `--version` 和 `--help` 是否正常
- 核心 API 是否响应
- 数据库/存储是否可访问

**示例**：
```bash
npx @geminilight/mindos@latest --version
npx @geminilight/mindos@latest --help
```

### 5.2 CHANGELOG 维护（每次发版）

**原则**：
- 每个正式版本都有 CHANGELOG
- CHANGELOG 描述"用户可见"的变化，不描述实现细节
- 分为：新增、功能变更、修复、性能优化、破坏性变更

**工具**：Conventional Commits + `release-please`、`changesets`

### 5.3 回滚预案（每次发版）

**问题**：新版本上线后出现严重问题，需要快速回滚。

**回滚预案内容**：
- 如何回滚到上一个版本
- 回滚需要多长时间
- 数据迁移是否需要考虑（数据库 schema 变更）
- 回滚后如何通知用户

---

## 六、维护节奏总览

| 维度 | 任务 | 节奏 |
|------|------|------|
| **文档** | 版本号对齐 | 每次发版前 |
| **文档** | Wiki/Docs 审计 | 每月 |
| **文档** | 双语文档一致性 | 每月 |
| **文档** | 依赖版本审计 | 每月 |
| **文档** | 知识沉淀（Known Pitfalls） | 每个 bugfix 后 |
| **代码** | 测试覆盖 | 每次 PR |
| **代码** | 死代码清理 | 每月 |
| **代码** | 大文件/长函数审计 | 每季度 |
| **代码** | 性能基线 | 每月 |
| **架构** | 边界审计 | 每个大版本 |
| **架构** | 安全检查 | 每次 PR + 每月 |
| **架构** | 设计系统合规 | 每次前端 PR |
| **发布** | 冒烟验证 | 每次发版后 |
| **发布** | CHANGELOG 维护 | 每次发版 |
| **发布** | 回滚预案 | 每次发版 |

---

## 七、落地建议

### 第一步：最小化可行维护

不要一开始就追求完整维护体系。从最高 ROI 的两项开始：

1. **版本号一致性检查**（CI 自动化，成本最低，收益最高）
2. **每个 bugfix 后写 Known Pitfalls**（成本最低，防止重复踩坑）

### 第二步：建立节奏

- 每月：文档审计 + 依赖审计 + 死代码清理
- 每季度：大文件审计 + 边界审计 + 类型安全审计 + 性能基线
- 每个大版本：架构边界审计 + 安全全面检查

### 第三步：工具化和自动化

- CI 中集成尽可能多的检查
- 让维护成本降到最低（自动化 > 人工）

---

## 八、模板和工具链推荐

| 场景 | 推荐工具 |
|------|---------|
| 依赖安全 | `npm audit`、`Snyk`、`Dependabot` |
| 依赖更新 | `Renovate`、`Dependabot` |
| 循环依赖检测 | `madge`、`dependency-cruiser` |
| 测试覆盖率 | `Jest coverage`、`Codecov` |
| 死代码检测 | `typescript-eslint --no-unused-vars`、`sonarqube` |
| CHANGELOG 生成 | `release-please`、`changesets`、`Keep a Changelog` |
| API 文档 | `Swagger`、`OpenAPI`、`typedoc` |
| 版本号检查 | `git-tags` + 自定义脚本 |

---

## 九、何时重新审视维护策略

- 项目经历重大架构变更（重构、迁移）
- 项目规模显著增长（团队人数、代码量、用户量）
- 维护成本明显上升（bug 数量、回归问题增多）
- 外部环境变化（新语言版本、新依赖策略）

---

> 维护不是一次性工作，而是持续的投资。每次发版、每个 bugfix、每个季度回顾，都是在积累项目的长期健康度。