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`

颜色如何计算

confidence = min( evidence , freshness , weakest dependency , contradiction )

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

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

笔记的解剖

---
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 查看器

各标签页：保险库（你的笔记，各带其颜色）、新鲜度（哪些即将过期，带重新验证按钮）、Pack（把某个主题的笔记组装成一个着色的上下文块，供粘贴给 AI）、图谱（笔记之间如何关联）、审查（断链、过期笔记、矛盾）、Guard 和真实性。

所有运维操作都在查看器的 kebab 菜单里——不需要终端：MCP 连接（按应用签发／吊销具名令牌，带有效期和只读模式）、回收站（恢复或永久删除）、MCP 审计 （谁在何时、从哪个 IP 调用了哪个工具）、证据根目录（每个项目的证据相对哪个文件夹解析）、导出（备份）（整个保险库打包为 zip，不含机密）、智能体指令 （生成教会你的智能体这套协议的 AGENTS.md/CLAUDE.md）以及设置 · AI 模型。

Guard，逐步说明

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

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

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

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

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

CLI

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

可选配件（默认关闭）

没有以下任何一项，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 上查看