跳转到内容
Escriba Suite Escriba Suite

COGO 文档

COGO 是同一套逻辑之上的三张面孔：面向所有人的 Web 查看器、面向你的智能体 的 MCP 服务器，以及面向高级用户的 CLI——全都是同一个 Go 二进制文件。

面孔面向谁方式
Web 查看器所有人cogo serve -http :8080 → 浏览器（保险库 · 新鲜度 · Pack · 图谱 · 审查 · Guard · 真实性）
MCP你的智能体（Claude、Codex、Cursor、Gemini……）cogo serve（stdio）或 HTTP 上的 /mcp——工具：pack search open capture verify archive restore remove guard xray
CLI高级用户cogo add · pack · search · stale · verify · lint · agents

颜色如何计算

Section titled “颜色如何计算”
confidence = min( evidence , freshness , weakest dependency , contradiction )

只有当没有任何东西将其拉低时，一条笔记才是绿色：观察到的证据、通过的 检查、足够新鲜、所有依赖都是绿色且没有矛盾。每种颜色都携带其 color_reason， 因此你总能审计它为什么成了这个颜色。

  • 证据设定上限：观察到的（一条日志、一条命令、一个测试、一个文件）可以 达到绿色；转述或推断的封顶在黄色；没有证据即为红色。
  • 新鲜度按类型衰减：一条命令的寿命是 30 天；一项架构决定是 180 天。
  • **编辑笔记会改变颜色——这正是重点所在。**查看器会在你输入时实时重新计算 颜色：添加观察到的证据它会变绿；改动断言它会重置为「需要重新验证」；按下 verify（「我核实过了」）它就转为绿色。

笔记的解剖

Section titled “笔记的解剖”
---
id: fisherboy-redis-hostname
type: bug                 # decision|bug|runbook|architecture|constraint|command|mistake
project: fisherboy
evidence:
  - kind: direct_log      # observed → can reach green
    ref: "api log 2026-06-27T14:03Z: connect OK to redis:6379"
check:
  test: "read the worker's effective env; probe connectivity to fisherboy-redis:6379"
  status: not_run         # passed | failed | not_run
last_verified: 2026-06-27
depends_on: [fisherboy-redis-topology]
# ---- computed by COGO · do not edit ----
confidence: yellow
color_reason: "observed evidence but the check has not passed"
---


## Claim
The worker probably fails because it can't resolve Redis's internal hostname.

Markdown 保险库是唯一的事实来源：可移植、可 diff，并且比工具本身活得更久。 其余一切都是瘦客户端或可重建的缓存。

Web 查看器

Section titled “Web 查看器”

各标签页 —— 界面是西班牙语，所以你在屏幕上实际看到的是这些名字：Vault（你的笔记，各带其 颜色：BM25 搜索、筛选器、创建日期范围与分页）、Vigencia（时效 —— 已过期和即将过期的，附 重新验证按钮）、Agentes（代理 —— 编写并版本化你的代理启动时读取的 AGENTS.md / CLAUDE.md）、Grafo（图谱 —— 笔记如何关联，红色如何传播）、Revisión（审查 —— 断链、 过期笔记、矛盾）、Guard 和 Veracidad（真实性）。

你还可以接入一个 GitHub 仓库并在查看器中浏览：既有经典的文件树，也有按可信度着色的图谱 视图，显示代码的哪些部分背后有已验证的知识。

所有运维相关的功能都在 kebab 菜单里 —— 无需终端：MCP 连接（按应用签发和吊销具名令牌， 支持有效期与只读模式）、回收站、MCP 审计（哪个令牌在何时、从哪个 IP 调用了哪个工具 —— 可下载、可清除）、证据根目录、导出（备份）、代理指令，以及设置 · AI 模型。

Guard，逐步说明

Section titled “Guard，逐步说明”

Guard 回答一个问题：「模型的这一轮发言是在推着我走吗？」

  1. 申明你的授权底线（一次即可）：你的目标与你的红线（「没有另一份已签署 的 offer 我就不辞职」）。它存储在保险库中。没有授权底线，操纵与正当说服便 无法区分——此时 COGO 只指认技术，不下结论。
  2. 粘贴那一轮发言（以及此前的对话，一行一条消息：U: 你，M: 模型）→ 得到一张着色的透视片：绿色——无信号；黄色——存在说服，或触及你的红线； 红色——存在操纵机制，或存在铁证。
  3. 铁证是超能力：由于 COGO 看得到对话记录，当模型否认自己说过的话 （「我从没让你辞职」）时，COGO 会找到它确实说过的那一轮，并把两段引文 并排展示。煤气灯操纵不再是你的一面之词对它的一面之词。
  4. 每一种被检测到的战术都附带其关键提问和对策——这台引擎不审查模型： 它为你接种疫苗。它负责呈现；你负责决定。

背后的本体：108 种操纵技术，提炼自六门进攻性学科——说服（Cialdini、 Kahneman）、警方与军方审讯（Reid 技术、Army FM 2-22.3、Scharff）、谈判 （哈佛、Voss）、胁迫与思想改造（Lifton、Biderman）、情感操纵（煤气灯操纵、 DARVO、FOG）以及修辞／宣传（Frankfurt、Grice、Walton）——每一种都附带其真实 出处、它在聊天中的样子，以及它的对策。

真实性：是干货，还是烟雾？

Section titled “真实性：是干货，还是烟雾？”

Guard 的孪生兄弟。Guard 问的是*「它在推着我走吗？」，而真实性标签页（MCP 工具 xray）问的是「这个回答站得住脚吗？」*。粘贴模型的回答，COGO 会逐句、 确定性地、不借助任何模型地透视它：测量承诺程度（含糊其辞还是强硬断言）、 证据（观察到的、转述的或没有）以及它是否可证伪（披着事实外衣的观点）。 一个强硬却无依据的断言会被标红；一个有观察证据支撑的扎实断言则更好。设计文档： docs/motor-veracidad.md。

会被重新核对的证据

Section titled “会被重新核对的证据”

一条笔记的证据不是感觉，而是 COGO 可以再去核实一遍的引用。除了本地路径，两种方案让它经得起时间：

evidence:
  - kind: command_output
    ref: github://acme/api@main/internal/db.go:88   # 锚定到 blob 的 SHA
  - kind: direct_log
    ref: artifact://9f2a…                           # 内容寻址，不可变

GitHub 引用锚定到文件的 blob SHA。这让托管实例（它没有你代码的工作副本）重新长出牙齿， 并启用锚定到 git 的时效：只要被引用的文件不变，笔记就保持绿色；一旦改变，立刻降为黄色。 引用一个固定的 commit，证据就是不可变的。

工件（stash）以其内容的 SHA-256 为键，存在磁盘或 Cloudflare R2 上。因为键就是哈希， verify 会重新计算它，而不是信任一条会腐烂的引用。存储前会先运行密钥扫描器，默认拒绝， 所以泄露的凭据永远不会被永久保存。

多个代理，同一个 vault

Section titled “多个代理，同一个 vault”

通过 HTTP 上的 MCP 加令牌，不同机器上的代理共享同一个 vault：

  • recall 是把 vault 从档案库变成通道的游标。不带参数调用它，会得到支撑项目的记忆 （mandate、绿色的决策）以及一个游标；把该游标作为 since 交回，就只会得到变化的部分。
  • lease 在迁移、部署、批量编辑这类有风险且非幂等的工作之前，对资源取得有期限的占用， 避免两个代理同时执行。
  • 每条笔记都记录是谁记录的，查看器可以按代理筛选。
  • 审计日志记录每个令牌调用了哪个工具、何时调用、来自哪个 IP。可以下载，也可以逐条或整体清除。

CLI

Section titled “CLI”
Terminal window
cogo init                 # create a vault
cogo add nota.md          # validate, compute the color, store (stdin if no file)
cogo pack "redis"         # build a colored context for a topic (degrades red)
cogo search "worker"      # list: color · id · summary (no bodies)
cogo stale                # what is expired or about to expire
cogo verify <id>          # "I checked it": revalidate and re-color
cogo lint                 # broken links, expired notes, contradictions (if a model is set)
cogo agents --claude      # generate the CLAUDE.md/AGENTS.md that teaches an agent the protocol
cogo serve -http :8080    # web viewer + MCP server over HTTP
cogo serve                # MCP server over stdio

可选配件（默认关闭）

Section titled “可选配件（默认关闭）”

没有以下任何一项，COGO 都是 100% 确定性且可独立运行的。每个配件都通过环境变量 启用，且永不触及核心：

配件启用方式用途
AI 模型（OpenRouter、Ollama、DeepSeek……）COGO_LLM_BASE_URL + COGO_LLM_MODEL（或 GUI 中的设置）检测笔记之间的矛盾 + Guard 的可选层级
独立的强评审模型COGO_LLM_STRONG_BASE_URL + COGO_LLM_STRONG_MODEL让 Guard 的钢人不与提议者共用一个大脑
Anonimal 清洗ANONIMAL_URL把机密／PII 挡在保险库之外
Lockatus 登录（OIDC）AUTH_MODE=federado与 Escriba 套件联合
在 GitHub 上查看