docs: 维护两个新的文档

2026-06-15 12:55:51 +00:00 · 2026-04-03 11:01:17 +08:00
parent 5278ce1f3a
commit 8e4aea45a8
4 changed files with 156 additions and 8 deletions
--- a/README.md
+++ b/README.md
@@ -12,16 +12,16 @@
  - [x] 构建流水线完成, 产物 Node/Bun 都可以运行
 - [x] V3 会写大量文档, 完善文档站点
 - [x] V4 会完成大量的测试文件, 以提高稳定性
-  - [x] Buddy 小宠物回来啦
-  - [x] Auto Mode 回归
+  - [x] Buddy 小宠物回来啦 [文档](https://ccb.agent-aura.top/docs/features/buddy)
+  - [x] Auto Mode 回归 [文档](https://ccb.agent-aura.top/docs/safety/auto-mode)
  - [x] 所有 Feature 现在可以通过环境变量配置, 而不是垃圾的 bun --feature
 - [x] V5 支持企业级的监控上报功能, 补全缺失的工具, 解除限制
  - [x] 移除牢 A 的反蒸馏代码!!!
-  - [x] 补全 web search 能力(用的 Bing 搜索)!!!
-  - [x] 支持 Debug
+  - [x] 补全 web search 能力(用的 Bing 搜索)!!! [文档](https://ccb.agent-aura.top/docs/features/web-browser-tool)
+  - [x] 支持 Debug [文档](https://ccb.agent-aura.top/docs/features/debug-mode)
  - [x] 关闭自动更新;
-  - [x] 添加自定义 sentry 错误上报支持
-  - [x] 添加自定义 GrowthBook 支持 (GB 也是开源的, 现在你可以配置一个自定义的遥控平台)
+  - [x] 添加自定义 sentry 错误上报支持 [文档](https://ccb.agent-aura.top/docs/internals/sentry-setup)
+  - [x] 添加自定义 GrowthBook 支持 (GB 也是开源的, 现在你可以配置一个自定义的遥控平台) [文档](https://ccb.agent-aura.top/docs/internals/growthbook-adapter)
 - [ ] V6 大规模重构石山代码, 全面模块分包
  - [ ] V6 将会为全新分支, 届时 main 分支将会封存为历史版本

@@ -63,6 +63,16 @@ bun run build

 如果遇到 bug 请直接提一个 issues, 我们优先解决

+## Feature Flags
+
+所有功能开关通过 `FEATURE_<FLAG_NAME>=1` 环境变量启用，例如：
+
+```bash
+FEATURE_BUDDY=1 FEATURE_FORK_SUBAGENT=1 bun run dev
+```
+
+各 Feature 的详细说明见 [`docs/features/`](docs/features/) 目录，欢迎投稿补充。
+
 ## VS Code 调试

 TUI (REPL) 模式需要真实终端，无法直接通过 VS Code launch 启动调试。使用 **attach 模式**：
@@ -83,7 +93,8 @@ TUI (REPL) 模式需要真实终端，无法直接通过 VS Code launch 启动

 ## 相关文档及网站

-<https://deepwiki.com/claude-code-best/claude-code>
+- **在线文档（Mintlify）**: [ccb.agent-aura.top](https://ccb.agent-aura.top/) — 文档源码位于 [`docs/`](docs/) 目录，欢迎投稿 PR
+- **DeepWiki**: <https://deepwiki.com/claude-code-best/claude-code>

 ## Star History

--- a/docs/features/buddy.mdx
+++ b/docs/features/buddy.mdx
@@ -0,0 +1,87 @@
+---
+title: "Buddy 宠物系统"
+description: "Buddy 是 CLI 中的虚拟宠物伴侣，通过 /buddy 命令孵化、互动，会出现在输入框旁边陪伴你写代码。"
+keywords: ["buddy", "宠物", "companion", "伴侣", "虚拟宠物"]
+---
+
+## 概述
+
+Buddy 是 Claude Code 内置的虚拟宠物系统。在 REPL 中通过 `/buddy` 命令可以孵化一只随机生成的宠物伴侣，它会出现在输入框旁边，陪伴你的编码过程。
+
+> Feature Flag: `FEATURE_BUDDY=1`
+
+## 启用方式
+
+```bash
+FEATURE_BUDDY=1 bun run dev
+```
+
+孵化窗口：2026 年 4 月 1-7 日期间启动时，会在 REPL 顶部显示彩虹色的 `/buddy` 提示。4 月 7 日之后命令仍然可用，但不再自动提示。
+
+## 命令
+
+| 命令 | 说明 |
+|---|---|
+| `/buddy` | 查看当前宠物信息和属性 |
+| `/buddy hatch` | 孵化一只新宠物（首次使用） |
+| `/buddy rehatch` | 重新随机生成宠物（替换现有） |
+| `/buddy pet` | 撸宠物，触发爱心动画 |
+| `/buddy mute` | 静音宠物（隐藏） |
+| `/buddy unmute` | 取消静音 |
+
+## 宠物属性
+
+### 物种（18 种）
+
+| | | | |
+|---|---|---|---|
+| Duck | Goose | Blob | Cat |
+| Dragon | Octopus | Owl | Penguin |
+| Turtle | Snail | Ghost | Axolotl |
+| Capybara | Cactus | Robot | Rabbit |
+| Mushroom | Chonk | | |
+
+### 稀有度
+
+| 稀有度 | 星级 | 权重 |
+|---|---|---|
+| Common | ★ | 60% |
+| Uncommon | ★★ | 25% |
+| Rare | ★★★ | 10% |
+| Epic | ★★★★ | 4% |
+| Legendary | ★★★★★ | 1% |
+
+孵化时基于种子随机决定，存在极低概率出现 Shiny（闪光）变体。
+
+### 属性值
+
+每只宠物拥有 5 项属性（0-100）：
+
+- **DEBUGGING** — 调试能力
+- **PATIENCE** — 耐心程度
+- **CHAOS** — 混乱指数
+- **WISDOM** — 智慧值
+- **SNARK** — 毒舌度
+
+### 外观
+
+每只宠物还有随机的外观配件：
+
+- **眼睛**: `·` `✦` `×` `◉` `@` `°`
+- **帽子**: none, crown, tophat, propeller, halo, wizard, beanie, tinyduck
+
+## 数据存储
+
+宠物信息存储在 `~/.claude.json` 的 `companion` 字段中。宠物的外观属性（物种、稀有度、属性值等）基于用户 ID 的哈希确定性生成，不可通过编辑配置文件来篡改稀有度。
+
+## 相关源码
+
+| 文件 | 说明 |
+|---|---|
+| `src/commands/buddy/buddy.ts` | `/buddy` 命令处理 |
+| `src/buddy/companion.ts` | 宠物生成与加载 |
+| `src/buddy/types.ts` | 类型定义（物种、稀有度、属性） |
+| `src/buddy/sprites.ts` | 终端像素画渲染 |
+| `src/buddy/CompanionSprite.tsx` | React 组件（输入框旁显示） |
+| `src/buddy/useBuddyNotification.tsx` | 启动提示通知 |
+| `src/buddy/prompt.ts` | 宠物相关 prompt 模板 |
--- a/docs/features/debug-mode.mdx
+++ b/docs/features/debug-mode.mdx
@@ -0,0 +1,48 @@
+---
+title: "Debug 模式"
+description: "通过 VS Code attach 模式调试 CLI 运行时，支持断点、单步执行和变量查看。"
+keywords: ["debug", "调试", "VS Code", "inspect", "断点"]
+---
+
+## 概述
+
+TUI (REPL) 模式需要真实终端，无法直接通过 VS Code launch 启动调试。使用 **attach 模式**连接到正在运行的 Bun 进程。
+
+## 步骤
+
+### 1. 终端启动 inspect 服务
+
+```bash
+bun run dev:inspect
+```
+
+会输出类似 `ws://localhost:8888/xxxxxxxx` 的地址。
+
+### 2. VS Code 附着调试器
+
+1. 在 `src/` 文件中打断点
+2. F5 → 选择 **"Attach to Bun (TUI debug)"**
+
+> **注意**：`dev:inspect` 和 `launch.json` 中的 WebSocket 地址会在每次启动时变化，需要同步更新两处。
+
+## 原理
+
+`dev:inspect` 脚本实际执行的是：
+
+```bash
+bun --inspect-wait=localhost:8888/<token> run scripts/dev.ts
+```
+
+Bun 的 `--inspect-wait` 参数启动一个 Chrome DevTools Protocol 兼容的 inspect 服务，等待调试器连接后才开始执行。VS Code 的 `bun` 扩展通过 WebSocket 连接到这个地址实现 attach。
+
+## JetBrains IDE
+
+理论上 JetBrains 系列（WebStorm / IntelliJ 等）也支持 attach 到 Bun inspect 服务（Run → Attach to Process），但尚未实际验证过。如果你验证成功，欢迎补充文档。
+
+## 相关文件
+
+| 文件 | 说明 |
+|---|---|
+| `package.json` → `dev:inspect` | 启动 inspect 服务的 npm script |
+| `.vscode/launch.json` | VS Code attach 调试配置 |
+| `scripts/dev.ts` | dev 模式入口，注入 MACRO defines |
--- a/mint.json
+++ b/mint.json
@@ -109,7 +109,9 @@
        "docs/internals/growthbook-adapter",
        "docs/internals/sentry-setup",
        "docs/internals/hidden-features",
-        "docs/internals/ant-only-world"
+        "docs/internals/ant-only-world",
+        "docs/features/debug-mode",
+        "docs/features/buddy"
      ]
    }
  ],