不是安全沙箱——是认知容器。
English | 中文
⚠️ 安全说明本插件仅在包含
.serenity标记文件的目录中完全激活。在其他目录中启动 OpenCode，它对 OpenCode 的原生行为零影响：
- 不注入系统提示
- 不安装路径隔离
- 不控制 bash
- 不激活任何工具
可放心全局安装。只有当你主动进入一个 CCC 目录时，宁静号才唤醒。
你使用 AI 编码助手。每次对话它都表现很好——但下次对话它什么都不记得。你要一遍遍重复上下文：
- "这个项目用 React + Vite..."
- "我们的命名规范是 camelCase..."
- "部署步骤是先 build 再 scp 到服务器..."
决策丢失。约定遗忘。每次从零开始。
因为你没有一个让 Agent 持续记忆的系统。
你需要两样东西：Node ≥ 20 和 OpenCode ≥ 1.16。
opencode plugin @shgroup/opencode-serenity-plugin该命令会自动安装 npm 包并写入 opencode 配置。或者用传统方式：
npm install @shgroup/opencode-serenity-plugin npx opencode-serenity-plugin install
然后打开 OpenCode，进入你想长期工作的目录，输入：
/serenity-init
TUI 会问你容器名称和描述。回答几个问题就完成了。
或者用 CLI：
opencode-serenity-plugin init /path/to/my-project \
--prefix my-project \
--description "管理我的 SaaS 项目代码、文档和开发流程"从安装到完成，不到一分钟。
你刚刚告诉 OpenCode："这个目录是我的工作区，记住它。"
插件在这个目录里创建了一个 .serenity 标记文件，以及配套目录结构：
my-project-serenity/
├── .serenity ← 标记：此目录是 CCC 边界
├── opencode.json ← OpenCode Agent 配置
├── AGENT_SESSIONS/ ← 工作会话自动存储
├── docs/ ← 设计方案文档
└── .opencode/
├── skills/ ← 领域知识（初始包含 3 个预装技能）
└── references/
这个带 .serenity 标记的目录叫做 CCC（Concrete Cognitive Container）——具体认知容器。
翻译成大白话：一个有边界的、有记忆的工作区。
- Agent 只能读写这个目录里的文件（不会跑出去乱翻你的系统）
- 每次对话的决策、约定、约束自动记录
- 你可以把领域知识写成 Skill，下次对话 Agent 自动加载
重启 OpenCode，输入任何消息。Agent 会进入一轮简短访谈（Phase 2），了解你的项目目的、Git 地址、工作项。访谈完成后，CCC 完全就绪。
/serenity-init 能工作，是因为你安装了一个插件。
这个插件是 ACC（Abstract Cognitive Container）——抽象认知容器。
| 名词 | 一句话 |
|---|---|
| ACC | 你安装的 npm 包。它定义了"认知容器应该有哪些工具和规则"。全局只有一个。 |
| CCC | 你创建的带 .serenity 的目录。它是 ACC 的运行时实例。你可以有多个。 |
就好像：
- ACC 是手机的出厂系统——定义了"手机应该能打电话、能装 App"
- CCC 是你的手机——具体装了什么 App、设了什么壁纸、联系人有哪些
升级插件（npm update），所有 CCC 自动获得新工具和新功能。因为 ACC 是共享蓝图，CCC 是独立实例。
安装后你获得 10 个工具，按设计目的分为五组。此外还有若干后台机制自动运行，无需手动调用。
裸 bash 不可记录、不可审计、容易越界。MSM（Mech & Semi-Mech）框架将常用操作注册为可执行单元，通过统一的安全通道执行。
msm_list— 查看当前 CCC 注册了哪些 MSM，以及它们的参数。msm_exec— 安全执行 MSM。路径逃逸自动阻断。优先于 bash 使用。msm_admin— 注册/注销 MSM。register自动 git commit。guide查看开发手册。check运行品质检查。
CCC 有明确的目录边界。Agent 对文件系统和版本控制的一切操作都限定在这个边界内。
cc-fs— 15 种文件操作（root/resolve/exists/list/tree/relative/mkdir/rm/mv/cp/touch/append/reveal/info/find），全部路径逃逸自动阻断。cc-git— 高频 Git 操作：status/commit/push/log/pull。非快进推送自动输出建议，冲突解决走 bash。acc_kit— ACC 通用能力工具包：health（三原则健康检查）/time（当前时间）/wait（等待 N 秒）。resident— 顶层常驻 agent（居民）：start/status/stop。双层循环，生命周期自我了结。
每次新对话 Agent 从零开始。会话系统把决策、进度、未解决问题沉淀为可追溯的记录。
session—create/use/close/list/show/summary/archive/health/qa。Agent 自动创建会话，自动记录决策，对话压缩或重启后仍可恢复上下文。
这两个工具不操作文件——它们提升 Agent 思考本身的品质。
eap— 认知质量框架。定义 E↑ / R↓ / S↑ 标准，指导每一次输出的外部可重建性。neat— 设计协作协议。小步对齐、显式决策、文档驱动，确保复杂设计的每一步可追溯。
loop— 循环执行工具。让 headless agent 在当前 CCC 下反复执行任务直到完成。自动管理专用 opencode serve 生命周期，每轮进度实时更新。--session <S101>（必需） — 指定工作会话，loop agent 自动继承会话上下文，进度写入该会话目录--label <名称>— 任务标签，用于进度文件命名- 模型从
.opencode/serenity.json的loop.defaultModel读取，未配置则报错 - 中断可恢复：从进度文件续跑，不重复已完成工作
以下机制在后台自动运行，无需手动调用。
-
Session-Keeper — 在主 agent 的非 headless 会话中，自动跟踪工具调用积分（write/edit=3分，task=10分，read/grep/glob/msm=1分）+ 经过时间（1分/分钟）。累计达到阈值时通过
tool.execute.after即时在工具返回中注入提醒（DCP 模式），要求模型回应[SESSION-KEEPER-recorded-{code}]或[SESSION-KEEPER-skipped-{code}]。提醒持续注入直至收到正确 code 的 ACK（text 或 reasoning part 均有效），ACK 后积分清零。会话恢复从历史消息中自动重建活跃会话。阈值通过.opencode/serenity.json的sessionKeeper.threshold配置（默认 150）。 -
Safe Mode — 安全模式禁用 bash 并激活写入黑名单。通过 TUI 斜杠命令
/serenity-safe-mode on|off|status控制，或直接创建/删除 CCC 根目录的.serenity-safe-on标记文件。黑名单规则在.opencode/serenity.json的safeMode.blacklist中配置，支持前缀匹配和正则表达式（regex:前缀）。 -
Loop Default Model — loop 工具的默认模型从
.opencode/serenity.json的loop.defaultModel读取，无需每次传递--model参数。
完整配置参考：在 TUI 中使用 msm_admin ccc-config 查看。
最关键的：你不必手动管理知识。知识在工作过程中自然增长。
你工作→产生决策、约束、领域经验
→ 自动沉淀在 SESSION.md（零操作成本）
→ 你判断哪些值得提炼为 Skill
→ 提炼为 SKILL.md 后，Agent 每次启动自动加载
→ 上下文更完整 → 效率更高 → 更多时间做新工作
→ 飞轮加速
这是知识的三层结构：
| 层 | 名称 | 谁写入 | 谁读取 | 积累成本 |
|---|---|---|---|---|
| L1 — Session | 默认沉淀层 | Agent（自动） | 你 + Agent（追溯时） | 零 |
| L2 — Skill | 选择性提炼层 | 你要求 Agent 写入 | Agent（每次启动自动加载） | 你判断成本 |
| L3 — MSM | 操作封装层 | 你注册 | Agent（通过 msm_exec） | 你注册成本 |
工作完成后，问 Agent 一句："哪些值得提炼为 skill？"——就够了。
以下几个安全机制自动生效，你不需要操心它们。
路径隔离（P3）： Agent 对文件系统的一切读写限定在 CCC 根目录内。它不会跑出去改你的系统文件。
Safe Mode（安全模式）： 安全模式下 bash 被禁用，且 write/edit 到黑名单路径的操作被拒绝。通过 /serenity-safe-mode on|off|status 控制，或在 CCC 根目录创建/删除 .serenity-safe-on 标记文件。黑名单规则由各 CCC 在 .opencode/serenity.json 中配置（支持前缀匹配和正则表达式）。
Subagent 继承： Agent 启动的子 Agent 自动继承全部约束——不可能通过子 Agent 绕过安全规则。
知识积累久了，自然会熵增——旧知识过时、新知识重复、约束冲突。
SQC（品质循环） 定期扫描所有 Skill 的质量：
- 自动修复可自动化的问题（引用断裂）
- 标记需要人工判断的项（冲突、孤儿技能）
- 推荐节奏：每周一次
sqc-tool pipeline
电影《宁静号》（Serenity）里有一艘飞船。不大，不新，但可靠。它在宇宙里飞，不可能知道每颗星球，但它有自己的船舱和航道。船员不知道每个货舱装了什么，但需要的时候总能拿到。
CCC 就是这样工作的：不是追求全知，而是追求可达。
Serenity 的工程基础是两门互补的理论学科：
"思维的功能价值与其外部可重建性成正比。"
EAP 定义认知产物的质量：每次输出的显式度（E↑）、重建成本（R↓）、稳定性（S↑）。你在 README 里读到的每个概念——ACC、CCC、Skill、MSM、Session——都是 EAP 在不同层面的具体化。
完整 EAP 理论：https://github.com/tellmewhattodo/theory-eap
"认知连续性工程是在有限资源与不可逆不确定性的约束下，维持一个认知实体的身份、可达性与演化能力的工程学科。"
EAP 回答"一段知识应如何被结构化"，CCE 回答"有结构的知识应如何跨时间持续演化而不丧失连贯性"。Serenity 的会话系统、会话追踪、熵管理机制（SQC）都是 CCE 的工程实现。
CCE 的核心主张：
- 连续性属于容器，而非任何个体参与者——智能体来来去去，但 CCC 的认知轨迹持续存在
- 组织必须至少与积累同步——否则操作化认知熵（H_op）无界增长，可达性丧失
- 重建优于保存——产物的价值由其使未来智能体重建原始推理的能力决定
完整 CCE 理论（中文）：https://github.com/tellmewhattodo/cognitive-continuity-engineering/blob/main/README.zh.md
把 Serenity 比作操作系统：
- ACC 是内核——声明认知容器应该有什么工具、规则、验证
- CCC 是用户态工作区——包含具体项目的技能、MSM、会话记录、项目文件
- EAP + CCE 是架构原则——指导认知系统的结构与演化
一个插件管理所有容器。每个 CCC 在自己的目录中，互不干扰：
~/projects/
├── saas-app/ ← CCC: SaaS 开发
├── ops-tools/ ← CCC: 运维工具
└── ai-lab/ ← CCC: AI 实验
同一 OpenCode 会话中，Agent 只能访问当前工作目录所属 CCC 的文件。
git clone git@github.com:tellmewhattodo/opencode-serenity-plugin.git
cd opencode-serenity-plugin
pnpm install
pnpm typecheck # TypeScript 类型检查
pnpm test # 487+ 测试（vitest）
pnpm build # 编译 + 复制模板
pnpm install # 安装到本地 ~/.config/opencode/详见 CHANGELOG.md
版本: v0.7.0 | 许可: MIT | 前置: Node ≥ 20, OpenCode ≥ 1.16