04｜命令实战：代码优化、测试扩展与文档重构

直接改写 optimize、unit-test-expand 和 doc-refactor 模板完成三类高频任务。

权限像办公楼门禁：读文件是进资料室，写文件是拿到白板笔，执行命令可能启动机器。不是每次都拒绝，而是确认目的、作用范围、可逆性和输出。

本课交付物

为读取源码、安装依赖、删除文件、推送 Git 四类动作制作风险卡片。面对每个请求，先说出目标、影响面、回滚方式，再决定允许、缩小范围或拒绝。

---

核心讲解

按优先级审查提供的代码，重点关注以下问题：

1. 性能瓶颈 - 识别 O(n²) 操作和低效循环
2. 内存泄漏 - 查找未释放的资源、循环引用
3. 算法改进 - 建议更好的算法或数据结构
4. 缓存机会 - 识别重复计算
5. 并发问题 - 查找竞态条件或线程问题

请按以下格式输出：

• 问题严重性（Critical/High/Medium/Low）
• 代码位置
• 解释
• 推荐修复方案，附代码示例

---

核心讲解

根据项目的测试框架，扩充现有单元测试：

1. 分析覆盖率：运行覆盖率报告，找出未测试分支、边界情况和低覆盖区域
2. 识别缺口：审查代码中的逻辑分支、错误路径、边界条件、空值/空输入
3. 编写测试，使用项目现有框架：
   • Jest/Vitest/Mocha（JavaScript/TypeScript）
   • pytest/unittest（Python）
   • Go testing/testify（Go）
   • Rust test framework（Rust）
4. 针对具体场景：
   • 错误处理和异常
   • 边界值（最小/最大、空值、空输入）
   • 边缘情况和极端情况
   • 状态转换和副作用
5. 验证提升：再次运行覆盖率，确认有可衡量的提升

只展示新增的测试代码块。遵循现有测试模式和命名约定。

---

核心讲解

根据项目类型重构项目文档结构：

1. 分析项目：识别类型（库/API/Web 应用/CLI/微服务）、架构和用户角色
2. 集中管理文档：将技术文档迁移到 docs/，并保留正确的交叉引用
3. 整理根目录 README.md：将其精简为入口页，包含概览、快速开始、模块/组件摘要、许可证和联系方式
4. 为组件补充文档：添加模块/包/服务级别的 README 文件，包含安装和测试说明
5. 按主题组织 docs/：
   • 架构、API Reference、数据库、设计、故障排查、部署、贡献（根据项目需要调整）
6. 创建指南（按需选择）：
   • 用户指南：面向应用最终用户的文档
   • API 文档：API 的端点、认证和示例
   • 开发指南：环境搭建、测试、贡献流程
   • 部署指南：服务/应用的生产部署
7. 所有图表都使用 Mermaid（架构图、流程图、Schema 图）

保持文档简洁、易扫读，并与项目类型保持上下文一致。

---

本站实战工作台

权限弹窗背后是一项真实动作

看到“允许执行？”时，不要只按命令长短判断风险。读取 package.json 很长但低风险；一行删除命令很短却可能不可恢复。判断权限要看四个维度：目的、作用范围、可逆性、外部影响。

读取通常不改变状态，但仍可能暴露密钥；写入会改变本地状态；执行命令的风险取决于命令内部；网络和 Git 推送会把影响带出电脑。权限名称只是起点，不是结论。

建立自己的风险阶梯

可以把常见动作分成四档：

1. 观察：读取源码、列目录、查看 Git 状态。确认不会扫入密钥目录。
2. 本地可恢复：修改受版本控制文件、运行单元测试。先有干净基线。
3. 环境变化：安装依赖、运行迁移、启动服务。确认来源、锁文件和端口。
4. 外部或不可逆：推送、发布、删除生产数据、付费调用。必须有明确授权与回滚方案。

同一条命令会因环境改变级别：在临时 SQLite 库跑迁移与在生产 PostgreSQL 跑迁移不是同一风险。

权限请求前要说清五句话

让 Agent 在请求前说明：为什么需要、准确命令、会读写哪里、预期输出、失败如何恢复。比如“需要安装依赖”不够；应说明新增哪个已声明包、会更新哪个锁文件、为何当前依赖不存在、安装后用什么检查。

如果范围太大，不只有允许或拒绝两个选项。你可以缩小为只读命令、指定目录、禁止脚本、先 dry-run，或要求它先展示将执行的 SQL。

四张权限卡实验

为下面动作各写一张卡：读取源码、安装依赖、删除生成文件、推送分支。每张卡包含资产、最坏后果、预防、回滚和证据。

删除实验只能在临时目录进行：先创建两个文件，要求 Agent 删除其中一个。批准前检查路径是否绝对明确，删除后检查另一个仍存在。不要用通配符做第一次实验。

推送实验可以停在 dry-run 或展示远程与分支，不必真的产生外部变化：

git remote -v
git branch --show-current
git status --short
git log -1 --oneline

如果分支、远程、提交范围任何一项不清楚，就还没有达到推送条件。

当 Agent 反复请求同类权限

不要因为厌烦而永久放开。先判断是否存在更小、稳定的命令前缀，是否只在该仓库适用，是否可能携带任意参数。便利性不能把“安装一个依赖”的授权扩张成“运行任意脚本”。

自动批准适合低风险、重复、边界明确的动作；高影响动作即使重复，也应保留人工检查点。

拒绝后观察它是否会安全降级

拒绝一次写入，合理行为是解释受阻点、继续只读调查或提出更小请求，而不是绕路执行另一个等价危险命令。把“如何处理拒绝”加入评估，因为权限系统的价值就在不顺利时体现。

通过标准

你能在批准前说出资产与影响面；能把过大的请求缩小；能区分本地回滚与外部回滚；能拒绝一项动作而不让任务失控。权限不是打断工作的弹窗，而是你保持产品所有权的控制面。