Skip to content

AGENTS.md

Latest commit

 

History

History
54 lines (44 loc) · 4.22 KB

AGENTS.md

File metadata and controls

54 lines (44 loc) · 4.22 KB
Raw

Cloud Code CLI — Repository Guide

Cloud Code CLI 是一个终端 AI coding agent，fork 自 kimi-code（MIT，见 LICENSE 与 NOTICE），大部分代码继承自上游，在其架构骨架上添加了一些有趣的功能。本文面向贡献者与代码阅读者。

有趣的特性（与上游的差异）

  • 多供应商账号体系：Kimi（OAuth/API key）+ ChatGPT Codex（OAuth，套餐用量/限额窗口/重置机会兑换）+ 完全自定义供应商与模型（/provider、/model 内置增删改）；子代理可独立设定模型（/model Alt+A）。
  • GUI 级 TUI：自研 bottom-slot 全屏架构 + 经典 inline 双模式；全鼠标支持（点击/悬停/虚拟滚动条/浮层对话框）、声明式命中区（HitRegistry）、DialogFrame 对话框骨架、搜索选择器、vim 模式、运行动效（blink + shimmer）。
  • Swarm 协作运行时：进程内 teammate（AsyncLocalStorage 身份隔离、共享任务列表、mailbox 协议、leader 权限桥、拓扑硬约束）+ coordinator 编排模式 + 子代理 fork（inherit_context）。
  • 工程深水区：git worktree 隔离（EnterWorktree/ExitWorktree）、渐进式上下文压缩（tool-result budget → pinpoint → full，触发核算精确到 provider usage）、投影缓存、前缀缓存纪律、session 恢复工程（图修复+中断续跑）、durable cron（项目级持久化+跨会话锁）、memdir（MEMORY.md 注入）、output styles（可插拔提示词风格）。
  • 插件生态：kimi-code 与 Claude Code 双格式插件、自定义 marketplace（git/github/url/local）、双 scope 启用。
  • 国际化：en + zh-CN 全量 i18n（编译期同形强制），工具输出结构化本地化通道（display/structured refs）。
  • 三通道分发：release（tag 正式版）/ beta（滚动 pre-release）/ dev（内部构建），/update 自更新（minisign 签名 + sha256 校验，信任根公钥随源码入库；dev 不发布故不签名）。验证全绿后自动发 beta（public-sync 推公开 main + 验收 cron），无需逐次确认，除非当批明确缓发。

仓库布局

apps/cloud-code        # CLI/TUI 主程序（npm 包 @cloud-teahouse/cloudcode-cli，bin 为 cloudcode/cloud-code）
apps/vis              # 会话回放可视化（vis-server + vis-web）
packages/
  agent-core          # agent 引擎：loop / session / permission / compaction / tools / swarm
  kosong              # 多 provider 抽象（kimi/anthropic/openai/google-genai 等）
  kaos                # 执行环境抽象（文件/进程操作唯一通道；含 sandbox/）
  node-sdk            # 公开 SDK / harness（@cloud-code/sdk）
  protocol            # 事件与协议类型
  server              # JSON-RPC 服务层（stdio，多连接宿主）
  transcript          # 转录
  pi-tui              # vendored 终端 UI 框架
  oauth / minidb
plugins/              # 插件与 marketplace.json
packaging/            # 发行物模板（AUR PKGBUILD 等）
scripts/              # install.sh 等

构建与测试

pnpm install
pnpm build          # 全量构建
pnpm test           # vitest 全量
pnpm run typecheck  # 全部包 tsc --noEmit
pnpm lint           # oxlint --type-aware（不允许新增 error）
pnpm -C apps/cloud-code run dev   # 开发模式跑 CLI

合并门禁：build + test + typecheck 全绿，lint 无新增 error。已知少数负载敏感测试（图片压缩、MCP 连接管理）在满载全量下偶发超时，隔离复跑为准。

约定

  • 品牌：产品名 "Cloud Code CLI"；bin cloudcode（cloud-code 为别名）；配置目录 ~/.cloud-code；环境变量 CLOUD_CODE_*。Moonshot 服务契约不可改：provider 字面量 "kimi"、managed:kimi-code、OAuth 凭证键/kimi-code.json、X-Msh-Platform header、KIMI_API_KEY、模型 ID、code.kimi.com。
  • i18n：en 为源，zh-CN 编译期强制同形；用户可见字符串必须过 t()。
  • 注释：简洁专业，写 WHY 不写 WHAT；禁止计划编号/批次标记/过程叙述。
  • 测试：组件 render-to-string 为主；视觉统一类改动须附渲染 parity 快照审查。
  • git：dev 为主分支；commit 小而专注；不主动 force push。