Skip to content

AGENTS.md

Latest commit

 

History

History
96 lines (67 loc) · 6.31 KB

AGENTS.md

File metadata and controls

96 lines (67 loc) · 6.31 KB
Raw

KimiCodeBar 交互规范

代码提交规范

  • 完成修改后，尤其是改动较多、涉及关键功能 / UI 重构 / bug 修复时，Agent 应直接执行 git commit 并 git push 推送到 GitHub，无需询问用户确认。
  • 推送前只暂存与本次修改相关的改动，不要把工作区中无关的未提交改动一并提交。
  • Commit message 使用中文，标题和正文都用中文，避免中英文混用。

平台规范优先

实现任何涉及系统组件、框架 API 或平台特定行为的功能前，先阅读对应系统的官方文档 / Human Interface Guidelines / API Reference，确认推荐用法。

案例：主题切换不要对 MenuBarExtra 内容视图使用 .preferredColorScheme()，这会触发 SwiftUI 运行时警告 Publishing changes from within view updates is not allowed。应通过 NSApplication.shared.appearance 控制应用整体外观，让 NSColor 动态配色自动适配。

Kimi CLI 命令参考

涉及 kimi 命令的改动前，必须先查阅官方文档确认命令的真实行为与参数，不要凭猜测实现：

构建验证规范

  • 写完代码后只做临时编译验证（xcodebuild build 确认编译通过）。
  • Debug/Release 已分叉（独立 Bundle ID、Debug 带 DEV 角标），本地产物与正式安装版完全隔离，不需要清理临时构建产物。
  • 不需要运行测试、也不需要启动 App 验证——维护者会自己用 Xcode 构建运行。

可点击元素反馈规范

所有可点击的 UI 元素必须同时满足：

  1. 鼠标悬停时显示手型光标（pointingHand）

    • 使用自定义 .cursor(.pointingHand) 扩展实现。
    • 即使是系统原生按钮（如 .borderedProminent）也需要显式添加。

  2. 鼠标悬停时提供高亮反馈

    • 改变背景色或前景色，让用户明确感知元素可点击。
    • 推荐：背景从 Color.white.opacity(0.08) 提升到 Color.white.opacity(0.14)，前景从 .kimiTextSecondary 提升到 .kimiTextPrimary。
    • 使用 @State private var isHoveredXXX 配合 .onHover { isHoveredXXX = $0 } 实现。

新增可点击元素时检查：

  • 是否添加了 .cursor(.pointingHand)？
  • 是否添加了 @State isHovered 状态？
  • 是否在 .onHover 中改变背景/前景色？
  • 禁用状态下是否移除了手型光标并降低视觉权重？

本地化规范（中 / 英双语）

App 支持应用内语言切换（跟随系统 / 中文 / English），机制见 macOS/KimiCodeBar/LanguageManager.swift：

  • 中文字面量即本地化 key，英文翻译维护在 macOS/KimiCodeBar/Localizable.xcstrings（String Catalog，编译进 en.lproj）。查不到译文时回退中文，界面不会出空白。
  • 新增用户可见文案时：
    • Text("中文") 一律写成 LText("中文")（自观察包装，语言切换自动重渲染）。
    • String 类型场景（组件 title 参数、枚举 displayName 等）用 languageManager.tr("中文")（View 内需有 @StateObject private var languageManager = LanguageManager.shared）或静态 LanguageManager.tr("中文")。
    • 插值用 %@（多个用 %1$@/%2$@），字面量 % 写 %%。
    • 同时在 Localizable.xcstrings 补上 en 翻译，术语与已有条目保持一致（如 加油包 Booster Pack、归档 Archive）。
  • 品牌名（Kimi / KimiCodeBar / Kimi Web）、菜单栏图形样式的 7D/5H 标注不做本地化。

版本号管理

  • App 版本读取 macOS/KimiCodeBar/Info.plist 的 CFBundleShortVersionString，代码中通过 Bundle.main.infoDictionary?["CFBundleShortVersionString"] 读取。
  • Info.plist 中的 CFBundleShortVersionString 已改为引用 $(MARKETING_VERSION)，CFBundleVersion 已改为引用 $(CURRENT_PROJECT_VERSION)。
  • 发版前修改 macOS/KimiCodeBar.xcodeproj/project.pbxproj，将 MARKETING_VERSION 与 CURRENT_PROJECT_VERSION 设为统一的版本号，例如都改为 1.3.1。Sparkle 自动更新会按该版本号判断是否需要更新，因此每次发版必须严格递增。
  • GitHub Release tag 使用 v{VERSION} 格式，例如 v1.0.0。
  • App 内「查看更新」跳转到 https://github.com/xifandev/KimiCodeBar/releases/。

Release Notes 规范

  • 不依赖 GitHub 自动生成的 Release Notes。
  • 每个版本整理 3~5 条核心更新点，由维护者复制到 GitHub Release body。
  • 一句话一条，不写细节堆砌，不写「修复了若干 bug」这类空话。
  • 只写用户可见、可感知的更新点：如功能新增、UI 交互优化、bug 修复。不写仓库内部维护项，如 CI 流程调整、文件命名规范、版本号管理方式等。

示例（v1.1.1）

## v1.1.1 更新内容

- 集成 Sparkle 自动更新框架（测试版），支持后台静默下载与 GitHub Releases 手动下载兜底。
- 适配 Kimi Code 0.28，Kimi Web 状态检测改为本地端口探测，启停逻辑同步更新。
- 优化底部版本卡片交互：悬停高亮、手型光标，点击直达 CLI 更新日志与 App Release。
- 修复加油包未启用时余额误显示估算金额的问题。
- 新增英文 README，官网支持中英文切换。

发版流程

Agent 执行发版时，按以下顺序操作：

  1. 更新版本号：修改 macOS/KimiCodeBar.xcodeproj/project.pbxproj，将 MARKETING_VERSION 与 CURRENT_PROJECT_VERSION 设为统一的新版本号（例如 1.3.6）。
  2. 更新更新日志：修改 CHANGELOG.md，在顶部写入 ## v{VERSION} 更新内容 及 3~5 条核心更新点（格式见「Release Notes 规范」）。
  3. 提交并打 tag：git add 相关文件，git commit，然后 git tag v{VERSION}，git push origin main v{VERSION}。
  4. 监控 GitHub Actions：确认 Build and Release workflow 全部步骤成功。
  5. 验证产物：下载 DMG 与 Sparkle zip，执行 codesign -vvv --deep --strict、spctl -a -t exec -vv、xcrun stapler validate 确认通过。
  6. 清理旧版本：删除不再需要的历史 Release 与 tag（仅保留最新版本及必要历史版本）。