跳到主要内容

Codely CLI 常用工作流指南

本文档总结了使用 Codely CLI 进行日常开发工作的常见工作流程，帮助你更高效地利用 AI 助手提升开发效率。

理解新代码库​

快速了解代码库概览​

当你刚加入一个新项目，需要快速理解其结构和架构时：

  • 导航到项目根目录
cd /path/to/project
  • 启动 Codely CLI
codely
  • 生成 CODELY.md
/init general  
# 如果是unity项目 请使用  
/init unity

深入了解特定组件​

这里使用了哪些主要的架构模式？  
关键的数据模型有哪些？  
认证是如何处理的？

提示：

  • 先从广泛的问题开始，再逐步聚焦到具体领域
  • 询问项目中使用的编码规范和模式
  • 要求提供项目专用术语的词汇表

完整恢复上一轮对话 /resume​

codely
> /resume

交互模式如果未开启新对话，可以直接通过 /resume 恢复上一轮会话信息。

查找相关代码​

当你需要定位与特定功能或特性相关的代码时：

  • 让 Codely CLI 查找相关文件
  • 获取组件如何交互的上下文信息
  • 理解执行流程

提示:

  • 明确说明你要查找的内容
  • 使用项目中的领域语言

高效修复 Bug​

当你遇到一个错误信息，需要找到并修复其来源时：

  1. 与 Codely CLI 分享错误信息
运行 npm test 时出现以下错误：[粘贴错误信息]
  1. 请求修复建议
建议几种修复 user.ts 中 @ts-ignore 的方法
  1. 应用修复
更新 user.ts 以添加你建议的 null 检查

提示：

  • 告诉 Codely CLI 重现问题的命令并获取堆栈跟踪
  • 提及重现错误的任何步骤
  • 让 Codely CLI 知道错误是间歇性还是持续性的

重构代码​

当你需要更新旧代码以使用现代模式和实践时：

  1. 识别需要重构的遗留代码
在我们的代码库中查找已弃用的 API 使用情况
  1. 获取重构建议
建议如何重构 utils.js 以使用现代 JavaScript 特性
  1. 安全地应用更改
重构 utils.js 以使用 ES 2024 特性，同时保持相同的行为
  1. 验证重构结果
运行重构代码的测试

提示：

  • 让 Codely CLI 解释现代方法的好处
  • 在需要时要求更改保持向后兼容性
  • 以小的、可测试的增量进行重构

使用专业子代理​

Codely CLI 提供了多个专业子代理来更高效地处理特定任务。

1. 查看可用的子代理​

/agents

此命令会显示所有可用的子代理，并允许你创建新的子代理。

2. 自动使用子代理​

Codely CLI 会自动将适当的任务委派给专业的子代理。

审查我最近的代码更改中的安全问题
运行所有测试并修复任何失败

3. 显式请求特定子代理​

使用 code-reviewer 子代理检查认证模块
让 debugger 子代理调查用户无法登录的原因

4. 创建自定义子代理​

在 .codely-cli/agents/ 中创建项目专用的子代理。

[agent]
id = "my-custom-agent"
description = "专门用于处理 X 任务的代理"

[agent.system_prompt]
role = "你是一个专业的 X 专家"
behavior = "当遇到 X 相关任务时，你应该..."

[agent.tools]
allowed = ["read_file", "write_file", "search_file_content"]

提示：

  • 使用描述性的 description 字段以启用自动委派
  • 将工具访问权限限制在每个子代理实际需要的范围内
  • 在项目目录中创建子代理以便团队共享

编写测试​

当你需要为未覆盖的代码添加测试时：

  1. 识别未经测试的代码
查找 NotificationsService.swift 中未被测试覆盖的函数
  1. 生成测试脚手架
为通知服务添加测试
  1. 添加有意义的测试用例
为通知服务中的边缘条件添加测试用例
  1. 运行并验证测试
运行新测试并修复任何失败

Codely CLI 会：

  • 检查你现有的测试文件，匹配已在使用的风格、框架和断言模式
  • 识别你可能遗漏的边缘情况
  • 建议对容易被忽略的错误条件、边界值和意外输入进行测试

创建拉取请求​

当你需要为你的更改创建一个文档完善的拉取请求时：

  1. 总结你的更改
  2. 使用 Codely CLI 生成拉取请求
  3. 审阅并优化
  4. 添加测试详情

提示：

  • 直接要求 Codely CLI 为你创建 PR
  • 在提交前审阅 Codely CLI 生成的 PR
  • 要求 Codely CLI 突出显示潜在风险或注意事项

处理文档​

当你需要为代码添加或更新文档时：

  1. 识别未文档化的代码
  2. 生成文档
  3. 审阅和增强
  4. 验证文档

提示：

  • 指定你想要的文档风格（JSDoc、docstrings 等）
  • 要求在文档中提供示例
  • 请求为公共 API、接口和复杂逻辑编写文档

引用文件和目录​

使用 @ 快速包含文件或目录，而无需等待 Codely CLI 读取它们。

引用单个文件​

解释 @src/utils/auth.js 中的逻辑

这会在对话中包含该文件的完整内容。

引用目录​

这会提供一个包含文件信息的目录列表。

@src/components 的结构是什么？

引用 MCP 资源​

显示来自 @github: repos/owner/repo/issues 的数据

这会使用格式 @server:resource 从已连接的 MCP 服务器获取数据。

提示：

  • 文件路径可以是相对路径或绝对路径
  • @ 文件引用会在文件所在目录及其父目录中添加 CODELY.md 到上下文中
  • 目录引用显示文件列表，而非文件内容
  • 你可以在单条消息中引用多个文件（例如，@file1.js 和 @file2.js）

恢复之前的对话​

Codely CLI 提供了两种恢复之前对话的方式：

1. 继续最近一次对话​

codely --continue

此命令将立即恢复你最近一次的对话，无需任何提示。

2. 在非交互模式下继续​

codely --continue --p "继续我的任务"

结合使用 --print 和 --continue 可以在非交互模式下恢复最近一次的对话，非常适合用于脚本或自动化流程。

3. 显示对话选择器​

codely --resume

此命令将显示一个交互式对话选择器，清晰地列出以下信息：

  • 会话摘要（或初始提示）
  • 元数据：已用时间、消息数量和 Git 分支

使用方向键导航并按 Enter 键选择对话。按 Esc 键退出。

提示：

  • 对话历史记录存储在本地计算机上
  • 使用 --continue 快速访问最近一次的对话
  • 使用 --resume 选择特定的历史对话
  • 恢复的对话将使用与原始对话相同的模型和配置

使用 Git Worktrees 运行并行会话​

当你需要同时处理多个任务，并且希望每个 Codely CLI 实例之间具备完全独立的代码环境时：

1. 了解 Git worktrees​

Git worktrees 允许你将同一仓库中的多个分支检出到不同的目录中。每个 worktree 都拥有独立的工作目录和文件，但共享相同的 Git 历史记录。

2. 创建新的 worktree​

# 创建一个带有新分支的新 worktree
git worktree add ../project-feature-a -b feature-a

# 或者基于现有分支创建 worktree
git worktree add ../project-bugfix bugfix-123

3. 在每个 worktree 中运行 Codely CLI​

# 导航至你的 worktree 目录
cd ../project-feature-a

# 在此隔离环境中运行 Codely CLI
codely

4. 管理你的工作树​

# 列出所有工作树
git worktree list

# 完成后删除工作树
git worktree remove ../project-feature-a

提示：

  • 每个工作树都有其独立的文件状态，这使其非常适合并行的 Codely CLI 会话
  • 在一个工作树中所做的更改不会影响其他工作树
  • 对于长期运行的任务，你可以在一个工作树中让 Codely CLI 进行工作，同时在另一个工作树中继续开发
  • 记得根据项目的设置，在每个新的工作树中初始化你的开发环境

将 Codely CLI 作为 Unix 风格工具使用​

添加到验证流程​

将 Codely CLI 用作 linter 或代码审查工具：

// package.json
{
  "scripts": {
    "lint:codely": "codely -p '你是一个 linter。请查看与 main 分支的差异，并报告任何与拼写错误相关的问题。在一行中报告文件名和行号，在下一行中描述问题。不要返回任何其他文本。'"
  }
}

提示：

  • 在 CI/CD 流水线中使用 Codely CLI 进行自动化代码审查
  • 自定义提示词以检查与你的项目相关的特定问题
  • 考虑为不同类型的验证创建多个脚本

管道输入，管道输出​

通过 Codely CLI 传输数据：

cat build-error.txt | codely -p '简洁地解释此构建错误的根本原因，并总结为 issue-troubleshooting.md'

提示：

  • 使用管道将 Codely CLI 集成到现有的 shell 脚本中
  • 与其他 Unix 工具结合使用，实现强大的工作流程
  • 考虑使用 --output-format 获取结构化输出

控制输出格式​

使用 --output-format 控制输出格式：

  • 文本格式（默认）
cat data.txt | codely -p '总结此数据' --output-format text > summary.txt
  • JSON 格式
cat code.py | codely -p '分析此代码中的 bug' --output-format json > analysis.json
  • 流式 JSON 格式
cat log.txt | codely -p '解析此日志文件中的错误' --output-format stream-json

Unity 项目开发工作流​

首先需要安装Codely Bridge。

Codely CLI 提供了强大的 Unity 集成功能，支持通过内置工具和 MCP 服务器与 Unity Editor 进行交互。

核心原则：状态 → 动作 → 验证 → 纠正​

  • 状态优先 - 在任何写操作之前，先调用 unity_editor.get_state 获取当前状态
  • 使用幂等操作 - 优先使用 ensure_* 操作确保配置正确
  • 编译验证 - 脚本更改后必须编译并通过控制台验证 0 错误
  • 确认更改 - 每次写操作后确认新状态再继续

常用 Unity 工作流​

1. 创建和修改脚本​

# 启动 Codely CLI
codely

# 创建新的 C# 脚本
创建一个名为 PlayerController 的脚本，包含基本的移动控制逻辑

# 修改现有脚本
修改 PlayerController.cs，添加跳跃功能

验证流程：

  • Codely CLI 会自动触发编译
  • 检查 Unity Console 是否有错误
  • 确认 0 错误后才继续

2. 场景管理​

打开 Assets/Scenes/MainScene.unity
创建一个名为 Player 的空 GameObject
为 Player 添加 Rigidbody 组件
保存场景

3. GameObject 和组件操作​

创建一个名为 Enemy 的 Cube
为 Enemy 添加 Mesh Collider
设置 Enemy 的材质为 Assets/Materials/EnemyMat.mat
将 Enemy 移动到位置 (0, 1, 0)

4. 资源管理​

创建一个新的材质 Assets/Materials/NewMaterial.mat
设置材质颜色为红色 (1, 0, 0, 1)
创建一个新的预制体 Assets/Prefabs/NewPrefab.prefab

5. NavMesh 和光照烘焙​

确保场景已保存
烘焙 NavMesh
烘焙光照

6. 使用专业子代理​

Codely CLI 提供了 Unity 专用的子代理。

使用 EditorModuleAgent 修改 UI 系统
使用 EditorPlanAgent 生成执行计划
使用 UnityCompileGateAgent 修复编译错误

Unity 开发最佳实践​

  • 始终从状态开始 - 在任何写操作前调用 unity_editor.get_state
  • 使用 ensure_ 操作 - 确保配置的幂等性
  • 编译后验证 - 脚本更改必须通过 Console 验证 0 错误
  • 关键边界保存场景 - 在烘焙、进入 Play Mode 前保存场景
  • 避免批量重导入 - 使用 ensure_* 而非 Assets/Reimport All
  • 遵循 Act → Confirm → Continue 循环 - 每次写操作后确认状态

询问 Codely CLI 的功能​

Codely CLI 内置访问其文档的功能，可以回答有关其自身特性和限制的问题。

示例问题​

  • Codely CLI 可以创建拉取请求吗？
  • Codely CLI 如何处理权限？
  • 有哪些斜杠命令可用？
  • 如何将 MCP 与 Codely CLI 一起使用？
  • 如何为 Amazon Bedrock 配置 Codely CLI？
  • Codely CLI 有哪些限制？
提示
  • Codely CLI 始终能够访问最新的文档
  • 提出具体问题以获得详细答案
  • Codely CLI 可以解释复杂功能，例如 MCP 集成、企业配置和高级工作流程

高级功能​

无头模式（Headless Mode）​

无头模式允许你以非交互方式使用 Codely CLI，非常适合脚本和自动化。

# 基本用法
codely -p "你的提示词"

# 从文件读取提示词
codely -f prompt.txt

# 管道输入
cat input.txt | codely -p "分析以下内容"

# 指定输出格式
codely -p "分析代码" --output-format json

# 使用特定模型
codely -p "你的提示词" --model qwen-max

# 恢复之前的对话
codely --continue -p "继续之前的任务"

审批模式（Approval Mode）​

审批模式要求你在 Codely CLI 执行某些操作前进行确认。

codely --approval-mode

在审批模式下，Codely CLI 会在执行以下操作前请求确认：

  • 修改文件系统
  • 运行 shell 命令
  • 执行 git 操作
  • 其他潜在危险的操作

MCP 服务器集成​

Codely CLI 支持 MCP（Model Context Protocol）服务器，可以扩展其能力。

# 启动 Unity MCP 服务器
npm run unity-mcp

# 使用 MCP 资源
显示来自 @unity: scene/active 的数据
显示来自 @github: repos/owner/repo/issues 的数据

总结​

Codely CLI 是一个强大的 AI 驱动命令行工具，可以显著提升你的开发效率。通过掌握这些常用工作流，你可以：

  • 快速理解新代码库
  • 高效查找和修复 bug
  • 安全地重构代码
  • 自动化测试编写
  • 简化 PR 创建流程
  • 管理 Unity 项目

记住这些关键原则​

  • 从理解开始 - 先了解代码库结构和约定
  • 使用专业工具 - 利用子代理和内置工具
  • 验证每次更改 - 运行测试、lint 和类型检查
  • 保持上下文 - 使用 @ 引用和对话恢复功能

祝你使用 Codely CLI 愉快！

  • PS.我们推出了 CLI nightly 版本，该版本包含最新功能，欢迎您试用。-