User Manual · 使用说明书

在飞书里跟一个机器人聊，
它能变成任何项目的智能体，
而且记得住、查得到、守规矩。

你的 Claude Code 跑在东京服务器上、接进飞书。用大白话就能造和管"按项目划分的 AI 助手"，每个助手带着那个项目的结构化上下文（背景 + 知识库 + 工作记忆），切过去就能干活。

部署 东京 VPS 认证 Claude Max 订阅 底层 lark-channel-bridge(MIT) 控制平面 agentctl 上下文 Context Package v1
00

为什么做这个

设计目标

核心目标：把"每个项目 / 领域"变成一个可对话、可累积、可治理的 AI 助手——而不是每次对着一个空白 ChatGPT 从头解释背景。

🎯

项目即助手

每个项目一个带专属上下文的 agent。跟它聊，它就懂这个项目的背景、资料、历史决策——不用每次重新交代。

🧩

上下文可组合、可治理

上下文不是 AI 随手生成的一篇，而是结构化、有索引、能累积的"知识包"，由可复用模块拼装。

🤖

用 Claude Code 本身做 agent

飞书只是入口，真正干活的是 Claude Code——能跑命令、读写文件、用工具，不只是聊天。

🔧

能被你和其他 agent 调度

造/管 agent 是一条命令；人、其他 agent、定时任务、未来的"元 agent"都能调。

01

一分钟看懂

一个 bot，多个项目

飞书里只有一个机器人。"不同项目的 agent"不是不同 bot，而是同一个 bot 切换不同项目的上下文：

你 · 飞书 私聊机器人 Claude CLI 助手 一个 bot 切上下文 · /cd 🛎️ 控制台（店长） 🗺️ roadmap 项目 💴 计费 项目 📝 公众号选题 项目
一个 bot · `/cd` 切到哪个项目目录，它就加载那个项目的上下文，变成那个项目的助手

① 一个 bot

所有对话都和 「Claude CLI 助手」进行。

② 一个店长

默认它是控制台：说"建个负责 X 的 agent"，它帮你建好。

③ 多个工人

每个项目一个带专属上下文的工人 agent，切进去就只懂它。

02

架构与原理

一条消息的旅程

从你的飞书消息，到服务器上真正干活的 Claude Code，再回到你——整条链路：

飞书 你发消息 bridge 网关 WebSocket 长连接 Claude Code cwd = 项目目录 跑命令 / 读写文件 上下文包 CLAUDE.md / 知识 / 记忆 加载 流式卡片回传（工具调用 + 答复） agentctl 控制平面 造/管上下文包
蓝=飞书 · 青=数据平面(干活) · 紫=上下文包 · 琥珀=控制平面(管事)

想看每一层的细节，点下面（可交互）：

你 · 入口飞书 App
私聊机器人，自然语言 / `/cd`
↓
数据平面bridge 网关
飞书 ⟷ Claude Code 的桥
↓
数据平面Claude Code
加载项目上下文包，干活
↺
控制平面agentctl
造/管项目 agent；装配上下文包
底座凭据 + 守护
token 落盘免登录 · systemd 守护
把鼠标移到（或点击）某一层看说明。
飞书数据平面控制平面
03

上下文包

一个项目 = 一个目录 = 一个知识包

这是整个系统的核心。一个项目的"上下文"不是随手生成的文字，而是一个固定结构、有索引、能累积的目录。关键在于把"总是加载的核心"和"按需读取的大块"分开（上下文窗口有限）：

CLAUDE.md · 核心 + 索引 每轮总是加载（小） 身份 · 领域背景 · 项目概述 · 约定 知识库索引（指向资料，不含全文） @memory/MEMORY.md（自动载入记忆） memory/MEMORY.md ④ 工作记忆 · 持久累积 @import → 每轮在上下文里 knowledge/ + index.md ⑤ 知识库 · 大块资料 按索引「按需读」 context/ · 静态可复用层（模块拼来） identity · domain · project · conventions .agent.json（元数据） Claude 的上下文窗口 CLAUDE.md 核心+索引（常驻） 工作记忆（@自动载入） 需要时才读进来的 某份 knowledge 资料 核心+记忆常驻； 大资料按需进出
左=磁盘上的包结构 · 右=运行时进 Claude 上下文窗口的内容（核心常驻、资料按需）

核心 vs 按需 关键

CLAUDE.md 只放核心+索引（总加载）；大资料放 knowledge/，按索引按需读。

结构 vs 内容 规范

结构固定；内容填进固定的槽（模块/你/AI 辅助）——不是每次自由生成一篇。

可组合的模块

6 个模块：公司背景、工程师/研究员/写作/运维、飞书规范。换一组=换人设。

04

怎么用

基本不用记命令

方式 A · 自然语言（推荐）

对默认 bot（控制台）说大白话，它一问一答：

  • 你："帮我建一个负责公众号选题的 agent"
  • 它问：项目名？干什么？用哪些模块？权限？
  • 确认后它自己跑 agentctl 建好
  • 把 /cd … 递给你，粘贴即进入

方式 B · 终端向导

SSH 进服务器，敲一个词，一行行问你：

SSH · 服务器
agentctl new   # 零 flag 交互向导
一行式
agentctl create --runtime bridge \
  --name "计费" --modules company-background,role-engineer \
  --purpose "阶梯计费+退款"
05

切项目，怎么切

点项目试试 ↓

切项目 = 给 bot 发一条 /cd <项目目录>。它切换工作目录并重置会话，之后带着那个项目的上下文跟你聊。点下面任意项目，看右边飞书里发生什么：

— 点一个项目，模拟在飞书里切过去 —

注意 切项目会重置当前会话。起别名：先 /cd，再 /ws save 名字，以后 /ws use 名字。
🦞
Claude CLI 助手● 控制台
06

记忆（现在真能记了）

写入 + 自动载入
你说"记住 X" 偏好 / 决策 agentctl memory add 真写进 MEMORY.md @import 载入 每轮自动进上下文 记得 跨会话/重启
同一段对话里记得
会话内 --resume，你前面说的它后面记得，直到会话被重置。
切项目 /cd重置
切项目会重置会话、在新项目从零开始（防串味）。
长期 / 跨重启记得
每个项目有持久 MEMORY.md：让它记偏好/决策→真写文件，@import 每轮载入→跨会话、跨重启都记得。每个项目各记各的。
07

使用场景

能拿来干嘛
📁

一个项目一个专属助手

"计费系统""公众号选题""某产品调研"各建一个，各带自己的背景和资料。切过去就能聊，不用重新交代、不串味。

📚

项目知识库问答

把资料 knowledge add 进去，agent 按需读、据此回答。资料多大都行——只进索引，用时才读。

🧠

越用越懂你

告诉它这个项目的偏好/决策，它写进 MEMORY，下次/重启后都记得。每个项目各记各的。

🏭

元 agent 造 agent

对控制台说"建个负责 X 的 agent"，它自己调 `agentctl` 造出来——动态生成、模块化组合。

🔌

被其他 agent / 定时任务调度

任何能跑 shell 的都能 `agentctl … --json` 驱动它；未来用定时器给某项目派活（如每早汇总）。

🧩

上下文模块化组合

不同项目复用"公司背景""工程师角色"等模块；某领域写一次背景，所有该领域项目共享。

08

质量闭环

怎么保证它真好用

有一套行为评估闭环：在真实 claude 上跑场景、断言行为、出分；失败就改上下文再回归，直到达标。当前 4/4 通过。

①期望 ②跑 ③评分 ④诊断 ⑤改 ⑥回归 闭环 直到达标无回归
S1 知识按需读 ✅ S2 记忆写入 ✅ S3 记忆召回 ✅ S4 范围遵守 ✅

闭环逼出过真问题——"agent 嘴上说记住其实没写""超范围还编造天气+假链接"——并验证修复有效（2/4 → 4/4）。加新能力就往评估里加场景，随时重跑看趋势。

09

运维与守护

不挂·自愈·可遥控

不挂

systemd Restart=always+限频；崩了 5 秒拉起，开机自启。

自愈

看门狗每 3 分钟体检；每天 04:30 主动重启，兜底"假死"。

护生产

MemoryMax=2G+OOM 保护：失控只 OOM 自己，不波及同机生产。

一个命令遥控（你或其他 agent 都用），重启不用重新登录：

ccgw · 服务器
ccgw status | restart | health | logs | reauth
安全 bot 能访问服务器所有文件，但只有你能驱动它。唯一铁律：别把它加进别人能看到的飞书文档、别授文档/评论权限。
10

命令速查

复制即用

飞书里发给 bot

飞书消息
帮我建个负责 X 的 agent       # 自然语言
/cd /home/ubuntu/cc-agents/main   # 回控制台
/cd /home/ubuntu/cc-agents/<项目>  # 进项目
/ws save 名字  ·  /ws use 名字   # 别名

服务器里跑（agentctl）

SSH
agentctl new                # 交互向导
agentctl list / modules      # 列 agent / 模块
agentctl knowledge add <名> <文件>  # 加资料入库+索引
agentctl memory add "<内容>"   # 手动写工作记忆
agentctl feishu <名>          # 打印进入它的 /cd

日常你几乎只用左边那栏 + 对"店长"说大白话；右边的命令"店长"会替你跑。