Skip to content
Back to search

Cohort

Local-first Agent Runtime connecting LLMs to controlled tools, Chrome, desktop automation, MCP, context governance, and verifiable memory.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/congchuanling-dot--cohort/badge.svg)](/listings/congchuanling-dot--cohort)

HTML

<a href="/listings/congchuanling-dot--cohort"><img src="/api/listings/congchuanling-dot--cohort/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

如果你要让 Cohort 操作网页,必须把 Cohort Browser Bridge 插件加载进 Chrome。npm 安装已经把插件文件放进本机,但 Chrome 出于安全限制,不允许 CLI 静默安装 unpacked extension,所以需要你手动加载一次。

先复制插件目录:

cohort extension path

输出通常类似:

.../node_modules/@cohort-ai/cohort/extension/cohort_browser_bridge

再打开 Chrome 扩展页:

cohort extension open

然后按下面步骤操作 Chrome:

1. 打开 `chrome://extensions` 2. 开启右上角的 `Developer mode` 3. 点击左上角的 `Load unpacked` 4. 选择刚才 `cohort extension path` 输出的目录 5. 确认扩展列表里出现 `Cohort Browser Bridge` 6. 打开任意普通网页,例如 `https://example.com`

验证插件是否连上:

cohort doctor computer

看到下面类似结果就表示可用:

[pass] browser.bridge.server: 127.0.0.1:18777/browser
[pass] browser.bridge.connection: connected

如果显示未连接,按顺序检查:

- Chrome 扩展页里插件是否启用。 - 是否已经打开普通 `http://` 或 `https://` 页面。 - 不要用 `chrome://extensions`、Chrome Web Store、浏览器设置页这类 Chrome 禁止扩展注入的页面测试。 - 如果端口被占用,退出旧的 `cohort` 进程后重试。

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,281 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <h1 align="center">Cohort</h1>
  3. <p align="center">
  4. <strong>Proof-Carrying Agent Runtime with Causal Replay and Runtime Governance</strong>
  5. </p>
  6. <p align="center">
  7. 面向真实任务的本地 Agent 运行时。
  8. <br />
  9. 录制可校验的执行轨迹,在隔离 Worktree 中分叉历史运行,并治理上下文、成本、缓存与工具风险,
  10. <br />
  11. 让 Agent 的执行、调试和改进都能携带证据。
  12. </p>
  13. </div>
  14. <p align="center">
  15. <img alt="Go" src="https://img.shields.io/badge/Go-1.21-00ADD8?style=flat-square&logo=go&logoColor=white">
  16. <img alt="Stage" src="https://img.shields.io/badge/stage-public%20preview-0F172A?style=flat-square">
  17. <img alt="License" src="https://img.shields.io/badge/license-MIT-16A34A?style=flat-square">
  18. <img alt="npm" src="https://img.shields.io/npm/v/@cohort-ai/cohort?style=flat-square&logo=npm&logoColor=white&color=CB3837">
  19. <img alt="LLM" src="https://img.shields.io/badge/LLM-OpenAI--compatible%20%2B%20Anthropic-4F46E5?style=flat-square">
  20. <img alt="Protocol" src="https://img.shields.io/badge/MCP-supported-111827?style=flat-square">
  21. <img alt="Browser" src="https://img.shields.io/badge/browser-Chrome%20Bridge-0F766E?style=flat-square">
  22. <img alt="Desktop" src="https://img.shields.io/badge/desktop-macOS%20AX-334155?style=flat-square">
  23. <img alt="Memory" src="https://img.shields.io/badge/memory-verified%20evolution-7C3AED?style=flat-square">
  24. </p>
  25. <p align="center">
  26. <b>简体中文</b>
  27. ·
  28. <a href="docs/readme/README.en.md">English</a>
  29. ·
  30. <a href="docs/readme/README.ja.md">日本語</a>
  31. ·
  32. <a href="docs/readme/README.ko.md">한국어</a>
  33. ·
  34. <a href="docs/readme/README.es.md">Español</a>
  35. ·
  36. <a href="docs/readme/README.fr.md">Français</a>
  37. ·
  38. <a href="docs/readme/README.hi.md">हिन्दी</a>
  39. </p>
  40. <p align="center">
  41. <img src="docs/1785215163755.jpeg" alt="Cohort preview" width="860">
  42. </p>
  43. <p align="center">
  44. <a href="#30-秒看懂-cohort">30 秒看懂</a>
  45. ·
  46. <a href="#产品界面与真实演示">产品演示</a>
  47. ·
  48. <a href="#核心能力">核心能力</a>
  49. ·
  50. <a href="#cohort-time-machine">Time Machine</a>
  51. ·
  52. <a href="#runtime-governor">Runtime Governor</a>
  53. ·
  54. <a href="#项目叙事">项目叙事</a>
  55. ·
  56. <a href="#为什么是-cohort">为什么是 Cohort</a>
  57. ·
  58. <a href="#快速开始">快速开始</a>
  59. ·
  60. <a href="#ai-api-接入">AI API 接入</a>
  61. ·
  62. <a href="#浏览器插件安装">浏览器插件</a>
  63. ·
  64. <a href="#可观测性接入">可观测性</a>
  65. ·
  66. <a href="#真实示例">真实示例</a>
  67. ·
  68. <a href="#当前边界">当前边界</a>
  69. ·
  70. <a href="#能力矩阵">能力矩阵</a>
  71. ·
  72. <a href="#系统架构">系统架构</a>
  73. ·
  74. <a href="#安全模型">安全模型</a>
  75. ·
  76. <a href="#项目结构">项目结构</a>
  77. ·
  78. <a href="docs/usage.md">使用文档</a>
  79. </p>
  80. ---
  81. ## 30 秒看懂 Cohort
  82. Cohort 是一个本地优先、证据驱动的 Agent Runtime。它不绑定模型厂商,而是把 OpenAI-compatible 或 Anthropic 模型接入可审计、可回放、可治理的执行系统。
  83. 你可以把它理解成 Agent 的运行时层:
  84. - 模型负责理解目标、规划步骤和调用工具。
  85. - Runtime 负责权限、工具边界、上下文容量、Provider 回执和安全恢复。
  86. - Time Machine 把请求、响应和工具观察录制成带 SHA-256 证明的 Replay Bundle。
  87. - 历史运行可以离线校验,也可以从指定 Turn 在隔离 Worktree 中分叉实验。
  88. ```bash
  89. npm install -g @cohort-ai/cohort@latest
  90. cohort init --provider deepseek # 或 local / anthropic
  91. export DEEPSEEK_API_KEY="sk-xxx"
  92. cohort doctor
  93. cohort --version
  94. cohort
  95. ```
  96. | 你得到什么 | Cohort 怎么做 |
  97. | --- | --- |
  98. | 可验证因果回放 | 录制 Replay Bundle,离线校验帧、运行时快照和聚合哈希 |
  99. | 反事实分叉实验 | 在指定 Turn 前复用历史证据,之后切换模型或 Prompt 并重复 Trial |
  100. | 运行时治理 | 区分 Provider 回执与本地估算,治理上下文容量、缓存、成本和重复失败 |
  101. | 真实执行闭环 | LLM 负责推理,runtime 负责工具、权限、证据和恢复 |
  102. | 浏览器自动化 | 通过 Chrome Bridge 读 DOM、执行 JS、点击、输入、等待和截图 |
  103. | 桌面 Computer Use | 基于 macOS Accessibility / AX 做窗口、控件、键盘和受控动作 |
  104. | 长任务能力 | session、history、compact、memory 分层管理上下文 |
  105. | 多 Agent 交付 | Acceptance Contract、隔离 Builder、Evidence、独立 Verifier、人工批准后事务合并 |
  106. | 可验证记忆 | 长期记忆必须引用工具证据,写入后回读确认 |
  107. | 可观测性 | 本地 `run.log.jsonl`,可选 Langfuse trace 上报 |
  108. > 我们并不缺新的聊天框。
  109. > 我们缺的是一个能解释“发生了什么”、验证“有没有被篡改”、实验“怎样会更好”的 Agent Runtime。
  110. ## 产品界面与真实演示
  111. Cohort 同时提供面向日常任务的终端体验,以及面向运行治理、证据检查和人工审批的本地控制中心。
  112. 两者读取同一份本地运行状态,不依赖云端控制面。
  113. ### Control Center
  114. <p align="center">
  115. <img src="docs/cohort_control_center.png" alt="Cohort Control Center overview" width="900">
  116. </p>
  117. <p align="center">
  118. <sub>统一查看本地数据源、Agent Sessions、评测结果、反思队列、因果追踪和待审批操作。</sub>
  119. </p>
  120. ### 命令行 Agent
  121. <p align="center">
  122. <img src="docs/cohort_cli.png" alt="Cohort command-line agent running an interactive task" width="860">
  123. </p>
  124. <p align="center">
  125. <sub>在终端中查看模型、工作区、Session 和工具状态,并以流式方式执行真实任务。</sub>
  126. </p>
  127. ### Time Machine
  128. <p align="center">
  129. <img src="docs/cohort_time_machine.png" alt="Cohort Time Machine replay and intervention view" width="900">
  130. </p>
  131. <p align="center">
  132. <sub>选择历史 Session 和 Replay Run,校验证据完整性,并从指定 Turn 创建隔离的反事实实验。</sub>
  133. </p>
  134. ### 浏览器自动化
  135. <p align="center">
  136. <a href="docs/cohort_browser_automation_demo.mp4"><strong>▶ 查看 4 分 22 秒真实浏览器自动化演示(MP4)</strong></a>
  137. </p>
  138. 演示展示 Cohort 通过 Chrome Bridge 完成页面读取、Shadow DOM 定位、真实 CDP 输入、
  139. 动作后验证和结果确认。公开版本已裁除终端原文,并对本机路径和账号信息做脱敏处理。
  140. ## 核心能力
  141. ### Cohort Time Machine
  142. Time Machine 把一次 Agent Run 变成可验证、可执行的实验:
  143. ```text
  144. Record -> Verify -> Fork -> Intervene -> Replay -> Compare -> Prove
  145. ```
  146. 每次正常运行都会保存模型请求与响应、工具调用与观察、运行时 Prompt、工具 Schema、Git 基线和工作区快照。Exact Replay 完全离线,不调用模型、工具或网络;它会校验帧级哈希、聚合哈希、请求/响应状态迁移和工具结果顺序,并在首个分歧点停止。
  147. ```bash
  148. cohort trace replay exact <session_id> --run <run_id>
  149. ```
  150. Fork Replay 在分叉点之前复用已录制的模型响应和工具观察,从分叉点开始切换到实时模型与工具。每个 Trial 都在独立 Git Worktree 中恢复基线与脏工作区快照,源 Session 不会被修改。
  151. ```bash
  152. cohort trace replay fork <session_id> \
  153. --run <run_id> \
  154. --fork-turn 7 \
  155. --model candidate-model \
  156. --system-prompt candidate.md \
  157. --repeat 5
  158. ```
  159. 实验报告包含成功率、Token、延迟、首个行为分歧点和 Proof Hash。前缀回放是确定性的;分叉后的实时后缀属于统计实验,因此需要通过重复 Trial 评估,而不是把一次成功当成稳定改进。
  160. 完整设计见 [Cohort Time Machine](docs/cohort_time_machine.md)。
  161. ### Runtime Governor
  162. Runtime Governor 使用同一份不可变 `run.log.jsonl` 证据流建立运行控制面:
  163. - **Provider Receipt Ledger**:区分 Provider 实际回执、本地估算和不可用状态,记录输入、输出、缓存 Token 与耗时。
  164. - **Context Capacity Governor**:解析模型窗口能力,保留输出与安全预算,展示 History、Memory、Compact 的 Context Waterfall。
  165. - **Executable Policy Engine**:对容量越界、重复同参失败、工具路由升级和高风险权限执行真实干预。
  166. - **Causal DAG**:把 Task、LLM、Tool、Decision 和 Artifact 重建为可下钻的执行证据图。
  167. - **Run Compare**:自动寻找相似成功基线,对比质量、Token、缓存、耗时和失败,并生成需要审批的优化 Proposal。
  168. ```text
  169. Provider Receipt + Context Build + Tool Evidence
  170. |
  171. v
  172. Causal DAG / Policy Engine
  173. |
  174. v
  175. Baseline Compare -> Proposal
  176. ```
  177. Governor 不猜测供应商价格,也不会把完整 Prompt 或工具结果暴露给控制台。缺失数据明确标为 unavailable,优化建议必须绑定当前 Run 和成功基线。
  178. 完整设计见 [Proof-Carrying Runtime Governor](docs/proof_carrying_runtime_governor.md)。
  179. ## 项目叙事
  180. 过去两年,Agent 领域最热闹的部分往往也是最脆弱的部分。
  181. 模型已经能写代码、能读网页、能理解复杂目标,甚至能在 benchmark 里看起来像一个“会做事的人”。
  182. 但一旦进入真实环境,问题很快暴露出来:
  183. - 它知道下一步该做什么,却没有稳定的执行路径。
  184. - 它可以调用工具,却没有足够强的约束、审计和恢复机制。
  185. - 它能记住一点东西,却记不清什么是事实、什么只是一次成功的幻觉。
  186. - 它能跑一段 demo,却很难跨过长任务、长上下文和真实副作用的门槛。
  187. 这就是 Cohort 想要解决的核心矛盾。
  188. 我们不是把大模型再包一层 UI,也不是再做一个提示词更花哨的 Agent 壳。
  189. 我们想做的是更底层的一层东西: 一个真正意义上的 <strong>Agent Runtime</strong>。
  190. 它的职责不是替模型思考,而是替系统建立秩序:
  191. - 给推理一个可执行的落点。
  192. - 给工具一个统一、受控、可恢复的运行边界。
  193. - 给长任务一个不会失控的上下文系统。
  194. - 给记忆一个可以被验证、被审计、被演化的生命周期。
  195. 如果说大模型提供的是 intelligence,
  196. 那么 Cohort 试图补上的,是 intelligence 落地之前最缺的那层 infrastructure。
  197. ## 为什么是 Cohort
  198. 大部分 Agent Demo 的问题不是“不会想”,而是“不能稳定做事”。
  199. - 模型能调用工具,但执行链路不可审计。
  200. - 上下文越来越长,最后只能硬截断。
  201. - 浏览器和桌面自动化混在 prompt 里,失败后很难恢复。
  202. - 记忆是模型随手写下的摘要,不是有证据的事实。
  203. Cohort 的判断很明确:
  204. > 真正可用的 Agent,不该建立在“模型这次刚好没出错”的侥幸上。
  205. > 它应该建立在 runtime 的边界、证据、恢复能力和长期演化能力之上。
  206. 所以 Cohort 的目标不是炫技式地证明“模型能做到什么”,而是工程化地回答另一个问题:
  207. **当 Agent 进入真实工作流之后,它如何持续、稳定、可追踪地完成任务。**
  208. | 方向 | Cohort 的处理方式 |
  209. | --- | --- |
  210. | 执行 | 用受控工具层连接文件、Shell、浏览器、桌面、MCP |
  211. | 长任务 | 用 session、compact、memory 分层管理长上下文 |
  212. | 可恢复 | 每次任务都有 `history.jsonl` 和 session 元数据 |
  213. | 可验证 | 长期记忆必须引用工具证据,写入后回读确认 |
  214. | 自动化 | 浏览器优先 DOM,桌面优先 AX,避免纯视觉瞎点 |
  215. | 演化 | SOP、checkpoint、memory candidate 分层升级,而不是一次性 prompt 魔法 |
  216. 换句话说,Cohort 关心的不是“像不像人”,而是更底层也更重要的三件事:
  217. - 能不能安全地行动。
  218. - 能不能在失败后恢复。
  219. - 能不能把一次性的成功沉淀成长期能力。
  220. ## 快速开始
  221. ### npm 安装后要做什么
  222. 一条命令安装 Cohort:
  223. 推荐使用 npm 官方 registry 全局安装。npm 包会从 GitHub Release 下载匹配当前 macOS 架构的 `cohort` 二进制并校验 SHA256,同时随包提供 Chrome Bridge 扩展、macOS desktop helper 和 OCR helper。当前已验证版本为 `v1.0.0`。
  224. ```bash
  225. npm install -g @cohort-ai/cohort@latest
  226. cohort --version
  227. ```
  228. 安装完成后按下面顺序配置:
  229. | 步骤 | 你要做什么 | 验收命令 |
  230. | --- | --- | --- |
  231. | 1 | 初始化模型 API 配置 | `cohort config` |
  232. | 2 | 设置对应 API key 环境变量 | `cohort doctor` |
  233. | 3 | 把 Chrome Bridge 插件加载进浏览器 | `cohort doctor computer` |
  234. | 4 | 授权 macOS Accessibility / Screen Recording | `cohort doctor computer` |
  235. | 5 | 启动交互式 Agent | `cohort` |
  236. ### 1. 配置 AI API
  237. Cohort 不是 DeepSeek 专用。它按 API 协议接入模型,当前原生支持两类:
  238. | 协议 | 适合接入 | provider |
  239. | --- | --- | --- |
  240. | OpenAI-compatible Chat Completions | DeepSeek、OpenAI、Ollama、LM Studio、OpenRouter、兼容 `/v1/chat/completions` 的网关 | `openai` |
  241. | Anthropic Messages API | Claude / Anthropic 原生 API | `anthropic` |
  242. 选择一组你要用的模型配置即可;如果要覆盖已有配置,再追加 `--force`。
  243. DeepSeek 或其他 OpenAI-compatible 云服务:
  244. ```bash
  245. cohort init --provider deepseek
  246. export DEEPSEEK_API_KEY="sk-xxx"
  247. ```
  248. 本地 OpenAI-compatible 服务,例如 Ollama / LM Studio:
  249. ```bash
  250. cohort init --provider local
  251. export LOCAL_OPENAI_API_KEY="local"
  252. ```
  253. Anthropic Claude:
  254. ```bash
  255. cohort init --provider anthropic
  256. export ANTHROPIC_API_KEY="sk-ant-xxx"
  257. ```
  258. 检查当前生效配置:
  259. ```bash
  260. cohort config
  261. cohort doctor
  262. ```
  263. 也可以直接编辑 `~/.cohort/config.yaml`,把 `llm.active_profile` 指向你要使用的 profile。完整写法见 [AI API 接入](#ai-api-接入)。
  264. ### 2. 安装 Chrome Bridge 插件
  265. 如果你要让 Cohort 操作网页,必须把 Cohort Browser Bridge 插件加载进 Chrome。npm 安装已经把插件文件放进本机,但 Chrome 出于安全限制,不允许 CLI 静默安装 unpacked extension,所以需要你手动加载一次。
  266. 先复制插件目录:
  267. ```bash
  268. cohort extension path
  269. ```
  270. 输出通常类似:
  271. ```text
  272. .../node_modules/@cohort-ai/cohort/extension/cohort_browser_bridge
  273. ```
  274. 再打开 Chrome 扩展页:
  275. ```bash
  276. cohort extension open
  277. ```
  278. 然后按下面步骤操作 Chrome:
  279. 1. 打开 `chrome://extensions`
  280. 2. 开启右上角的 `Developer mode`
  281. 3. 点击左上角的 `Load unpacked`
  282. 4. 选择刚才 `cohort extension path` 输出的目录
  283. 5. 确认扩展列表里出现 `Cohort Browser Bridge`
  284. 6. 打开任意普通网页,例如 `https://example.com`
  285. 验证插件是否连上:
  286. ```bash
  287. cohort doctor computer
  288. ```
  289. 看到下面类似结果就表示可用:
  290. ```text
  291. [pass] browser.bridge.server: 127.0.0.1:18777/browser
  292. [pass] browser.bridge.connection: connected
  293. ```
  294. 如果显示未连接,按顺序检查:
  295. - Chrome 扩展页里插件是否启用。
  296. - 是否已经打开普通 `http://` 或 `https://` 页面。
  297. - 不要用 `chrome://extensions`、Chrome Web Store、浏览器设置页这类 Chrome 禁止扩展注入的页面测试。
  298. - 如果端口被占用,退出旧的 `cohort` 进程后重试。
  299. ### 3. 检查桌面权限
  300. ```bash
  301. cohort doctor computer
  302. ```
  303. `doctor computer` 会检查 macOS Accessibility、Screen Recording、desktop helper、OCR helper、Chrome Bridge 和 artifact 目录;默认只读诊断,不会点击、输入或修改系统设置。
  304. 如果 Accessibility 或 Screen Recording 未授权,在 macOS 里给你运行 `cohort` 的终端授权:
  305. ```text
  306. System Settings
  307. -> Privacy & Security
  308. -> Accessibility / Screen Recording
  309. -> enable your Terminal / iTerm / VS Code
  310. ```
  311. ### 4. 启动 Cohort
  312. ```bash
  313. cohort
  314. ```
  315. 进入交互模式后直接输入任务,例如:
  316. ```text
  317. 读取当前项目 README,总结架构并指出安装步骤是否清晰
  318. 打开豆包网页,发送“你好”,观察它的回复
  319. 列出当前桌面窗口,告诉我哪些窗口可以被安全自动化
  320. ```
  321. 也可以执行一次性任务:
  322. ```bash
  323. cohort ask "读取 README.md,并用 8 条 bullet 总结 Cohort 的核心能力"
  324. ```
  325. 常用命令:
  326. ```bash
  327. cohort tools
  328. cohort config
  329. cohort session list
  330. cohort mcp list
  331. cohort mcp status
  332. cohort skill list
  333. ```
  334. ### 5. 其他安装方式
  335. 如果不想走 npm,也可以使用 GitHub installer:
  336. ```bash
  337. curl -fsSL https://raw.githubusercontent.com/congchuanling-dot/Cohort/master/scripts/install.sh | sh -s -- --repo https://github.com/congchuanling-dot/Cohort.git
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 450 on GitHub
  338. export PATH="$HOME/.cohort/bin:$PATH"
  339. ```
  340. 如果是在源码仓库内开发:
  341. ```bash
  342. git clone https://github.com/congchuanling-dot/Cohort.git
  343. cd Cohort
  344. ./scripts/install.sh
  345. export PATH="$HOME/.cohort/bin:$PATH"
  346. ```
  347. ### 6. 源码开发
  348. ```bash
  349. git clone https://github.com/congchuanling-dot/Cohort.git
  350. cd Cohort
  351. go run . config
  352. go run . tools
  353. go run . ask "读取 configs/config.yaml 并解释关键字段"
  354. go build -o cohort ./cmd/cohort
  355. ./cohort
  356. ```
  357. 默认项目配置见 [configs/config.yaml](configs/config.yaml)。全局运行时会按 `--config`、`COHORT_CONFIG`、项目配置、`~/.cohort/config.yaml` 的顺序查找配置。更完整的命令和 REPL 说明见 [docs/usage.md](docs/usage.md)。
  358. ## AI API 接入
  359. Cohort 的模型层按“协议”接入,而不是按单一厂商硬编码。只要服务兼容 OpenAI Chat Completions,通常都可以通过 `provider: openai` 接入;Anthropic Claude 使用 `provider: anthropic`。
  360. ### OpenAI-compatible 云服务
  361. 适合 DeepSeek、OpenAI、OpenRouter、兼容网关等服务。核心字段是 `api_base`、`api_key`、`model`。
  362. ```yaml
  363. llm:
  364. active_profile: deepseek
  365. profiles:
  366. deepseek:
  367. provider: openai
  368. name: deepseek
  369. api_key: ${DEEPSEEK_API_KEY}
  370. api_base: https://api.deepseek.com
  371. model: deepseek-v4-pro
  372. stream: true
  373. openai:
  374. provider: openai
  375. name: openai
  376. api_key: ${OPENAI_API_KEY}
  377. api_base: https://api.openai.com
  378. model: gpt-4.1
  379. stream: true
  380. ```
  381. 使用时切换 `active_profile`,并设置对应环境变量:
  382. ```bash
  383. export DEEPSEEK_API_KEY="sk-xxx"
  384. export OPENAI_API_KEY="sk-xxx"
  385. cohort config
  386. cohort doctor
  387. ```
  388. ### 本地模型:Ollama / LM Studio
  389. 只要本地服务暴露 OpenAI-compatible `/v1/chat/completions`,就可以这样配:
  390. ```yaml
  391. llm:
  392. active_profile: local
  393. profiles:
  394. local:
  395. provider: openai
  396. name: local
  397. api_key: ${LOCAL_OPENAI_API_KEY}
  398. api_base: http://127.0.0.1:11434/v1
  399. model: qwen3-coder
  400. stream: true
  401. ```
  402. 本地服务如果不校验 key,可以给一个占位值:
  403. ```bash
  404. export LOCAL_OPENAI_API_KEY="local"
  405. cohort doctor
  406. ```
  407. ### Anthropic Claude
  408. Claude 原生 Messages API 使用 `provider: anthropic`:
  409. ```yaml
  410. llm:
  411. active_profile: claude
  412. profiles:
  413. claude:
  414. provider: anthropic
  415. name: claude
  416. api_key: ${ANTHROPIC_API_KEY}
  417. api_base: https://api.anthropic.com
  418. model: claude-3-5-sonnet-latest
  419. stream: true
  420. ```
  421. ```bash
  422. export ANTHROPIC_API_KEY="sk-ant-xxx"
  423. cohort config
  424. cohort doctor
  425. ```
  426. ### 多模型与 fallback
  427. 可以把多个 profile 组合成主链路和备用链路:
  428. ```yaml
  429. llm:
  430. active_profile: deepseek
  431. fallback_profiles: [local, claude]
  432. profiles:
  433. deepseek:
  434. provider: openai
  435. api_key: ${DEEPSEEK_API_KEY}
  436. api_base: https://api.deepseek.com
  437. model: deepseek-v4-pro
  438. stream: true
  439. local:
  440. provider: openai
  441. api_key: ${LOCAL_OPENAI_API_KEY}
  442. api_base: http://127.0.0.1:11434/v1
  443. model: qwen3-coder
  444. stream: true
  445. claude:
  446. provider: anthropic
  447. api_key: ${ANTHROPIC_API_KEY}
  448. api_base: https://api.anthropic.com
  449. model: claude-3-5-sonnet-latest
  450. stream: true
  451. ```
  452. 当前原生支持范围是 OpenAI-compatible Chat Completions 和 Anthropic Messages API。Gemini 原生 API、Bedrock、Vertex、Azure OpenAI 特殊路径/鉴权还没有内置 adapter;如果这些平台提供 OpenAI-compatible 网关,可以先按 `provider: openai` 接入。
  453. ## 浏览器插件安装
  454. Cohort 的浏览器工具通过本地 Chrome Bridge 工作。CLI 会启动本地 bridge 服务,Chrome 扩展负责连接浏览器页面和本地 runtime。
  455. ```text
  456. cohort runtime <-> 127.0.0.1:18777/browser <-> Chrome Bridge extension <-> page DOM
  457. ```
  458. 安装方式:
  459. ```bash
  460. cohort extension open
  461. ```
  462. 这条命令会打开 `chrome://extensions`,并打印需要加载的扩展目录。你需要在 Chrome 扩展页中开启 `Developer mode`,点击 `Load unpacked`,选择该目录。
  463. 如果只想复制路径:
  464. ```bash
  465. cohort extension path
  466. ```
  467. 验证方式:
  468. ```bash
  469. cohort doctor computer
  470. ```
  471. 看到 `browser.bridge.connection: connected` 表示浏览器扩展已连上。若仍然显示未连接,先打开任意普通网页,例如 `https://example.com`;Chrome 扩展无法注入 `chrome://`、扩展商店、部分浏览器内部页和受浏览器策略限制的页面。
  472. ## 自适应工具路由
  473. Cohort 可以注册完整工具面,但不会把全部 schema 塞进每轮模型请求。Router 会按任务意图
  474. 渐进暴露工具;模型因能力不可见准备早停,或工具连续失败时,再自动升级完整工具面。
  475. 当前真实工具面测试:
  476. - 代码任务:81 → 15 个工具,schema payload 减少 82.6%。
  477. - 浏览器任务:81 → 33 个工具,schema payload 减少 63.5%。
  478. 不调用 LLM 即可预览路由:
  479. ```bash
  480. cohort tools route "分析 internal/agent/runner.go 并修复测试"
  481. cohort tools route "打开 https://example.com 检查登录按钮"
  482. ```
  483. Router 只控制模型可见性,不替代 Skill、MCP 和 Computer Use 的执行权限门禁。完整设计见
  484. [自适应工具路由](docs/adaptive_tool_routing.md)。
  485. ## 可观测性接入
  486. Cohort 默认提供本地可观测性,不依赖任何云平台。每次运行都会在 session 目录里保留可追踪证据:
  487. ```text
  488. temp/sessions/<session_id>/
  489. history.jsonl # 对话和工具结果事实来源
  490. run.log # 工具审计摘要
  491. run.log.jsonl # Runner 生命周期事件流
  492. memory.md # session memory
  493. compact.md # 长任务 compact 摘要
  494. ```
  495. 这些文件适合本地调试、问题复盘和离线反思:
  496. ```bash
  497. cohort session list
  498. cohort session resume <session_id>
  499. cohort trace graph last --open
  500. cohort reflect once --task tool-failure-report
  501. cohort reflect once --task session-archive
  502. cohort reflect status
  503. cohort reflect drain
  504. ```
  505. `trace graph` 会把 LLM、工具、权限、路由和文件副作用重建成因果 DAG,计算端到端
  506. 关键路径并生成不依赖云服务的交互式 HTML;也可用 `--json` 输出机器可读图结构。
  507. 实现与安全边界见 [Agent 因果追踪图](docs/causal_trace_graph.md)。
  508. 普通交互任务结束后,`SessionEnd` Hook 默认将轻量 trigger 写入持久反思队列。Hermes
  509. daemon 会批量生成 session archive、质量报告和 SOP/Skill candidate;该流程不调用 LLM,
  510. 也不会自动 promote:
  511. ```yaml
  512. reflection:
  513. auto_enqueue: true
  514. debounce_seconds: 30
  515. max_attempts: 3
  516. ```
  517. 如果你希望在网页平台查看 trace,可以接入 Langfuse。配置环境变量后,`cohort` 和 `cohort ask` 会把 Runner 生命周期、LLM 输入输出摘要、token usage 和工具事件上报到 Langfuse。
  518. ```bash
  519. export COHORT_LANGFUSE_ENABLED=true
  520. export LANGFUSE_HOST="https://cloud.langfuse.com"
  521. export LANGFUSE_PUBLIC_KEY="pk-lf-xxx"
  522. export LANGFUSE_SECRET_KEY="sk-lf-xxx"
  523. export COHORT_ENV="local"
  524. export COHORT_RELEASE="v1.0.0"
  525. cohort ask "读取 README.md,总结 Cohort 的可观测性能力"
  526. ```
  527. 也可以写入 `~/.cohort/config.yaml`:
  528. ```yaml
  529. observability:
  530. langfuse:
  531. enabled: ${COHORT_LANGFUSE_ENABLED}
  532. host: ${LANGFUSE_HOST}
  533. public_key: ${LANGFUSE_PUBLIC_KEY}
  534. secret_key: ${LANGFUSE_SECRET_KEY}
  535. environment: ${COHORT_ENV}
  536. release: ${COHORT_RELEASE}
  537. timeout_seconds: 2
  538. ```
  539. 安全边界:
  540. - `token`、`secret`、`password` 等敏感字段会脱敏。
  541. - `input_tokens`、`output_tokens`、`total_tokens` 等 usage 数值会保留,方便分析成本。
  542. - 截图、剪贴板正文和大段工具输出不会作为明文调试垃圾直接灌进 trace;本地 artifact 仍保存在 session/workspace 目录。
  543. - `reflect once` 是本地离线报告,不会自动补传到 Langfuse。
  544. ## 真实示例
  545. 证据驱动的软件交付可直接使用 CLI 闭环执行:
  546. ```bash
  547. cohort deliver plan "实现限流中间件并补齐并发测试"
  548. cohort deliver run <delivery_id>
  549. cohort deliver review <delivery_id> --open
  550. cohort deliver accept <delivery_id> --by "$USER"
  551. ```
  552. 系统会在隔离 worktree 中构建候选,完成 Integration Gate、独立 Verifier 和定向返修后进入
  553. 人工 Review。`accept` 使用 `--no-commit` 事务合并,并在 merge commit 上重新验证;
  554. Evidence 绑定 contract、Git tree、命令、环境和 Artifact hash。
  555. 下面的示例都建议在交互模式里执行。先启动 Cohort:
  556. ```bash
  557. cohort
  558. ```
  559. 然后在聊天框里直接输入任务。
  560. ### 1. 接手一个陌生仓库
  561. ```text
  562. 阅读 README.md、docs/README.md、go.mod 和 internal/app 目录,先总结这个项目的核心架构、启动链路和主要模块边界,再指出 5 个最值得优先改进的工程问题。每个问题都要给出依据文件、影响范围和建议修改方案。
  563. ```
  564. 这个任务适合首次接手项目、做技术调研、生成 onboarding 摘要或评估重构方向。Cohort 会通过受控文件工具读取仓库内容,把证据写入 session history,并在长任务里按需压缩上下文,而不是只凭 README 做表面总结。
  565. ### 2. 调试一个真实 Web 工作流
  566. ```text
  567. 打开本地 http://localhost:3000,等待页面稳定,读取 DOM 摘要和可交互元素。然后完成一次登录表单的可用性检查:确认输入框、提交按钮、错误提示、加载状态和成功跳转是否符合预期。不要只看截图,优先用 DOM、selector、URL 和文本证据验证;如果 DOM 信息不够,再降级到截图或 OCR。
  568. ```
  569. 这个任务更接近真实前端验收。Cohort 会走 `open -> wait -> snapshot/dom_summary -> act -> wait -> verify` 的闭环,避免“页面刚打开就判断成功”的脆弱流程。
  570. ### 3. 操作 macOS 客户端
  571. ```text
  572. 打开豆包客户端,观察当前窗口和可编辑输入区,起草一条“你好,帮我用一句话介绍 Cohort”的消息。先不要发送,先告诉我你定位到的输入框、将要执行的动作和需要我确认的风险点;如果我要你继续,再发送并观察对方回复。
  573. ```
  574. 这个任务展示的是桌面 Computer Use 的边界:Cohort 会优先使用 macOS Accessibility / AX 定位窗口和控件,只在 AX 不足时结合截图和 OCR;起草文本和发送动作会拆开处理,涉及外部副作用时需要确认,高风险动作会拒绝自动执行。
  575. ## 当前边界
  576. Cohort 当前已经适合做本地 Agent Runtime 的公开预览,但它不是一个“无限权限自动电脑人”。
  577. - 模型 API:原生支持 OpenAI-compatible Chat Completions 和 Anthropic Messages API;Gemini 原生 API、Bedrock、Vertex、Azure OpenAI 特殊鉴权/路径还没有原生 adapter。
  578. - 操作系统:Desktop Computer Use 当前聚焦 macOS;跨 OS driver 还在路线图里。
  579. - 浏览器:需要加载本地 Chrome Bridge 扩展。
  580. - 桌面:需要给运行 Cohort 的终端或 IDE 授予 Accessibility 和 Screen Recording 权限。
  581. - 安全:外部副作用动作需要确认;支付、审批、授权、登录验证、破坏性删除等高风险动作不自动执行。
  582. - 数据:session、日志、截图、记忆默认本地存储;启用外部 tracing 前应确认数据边界。
  583. - 回放:Exact Replay 验证录制证据,不重新执行历史副作用;Fork Replay 当前支持在分叉点切换模型或 System Prompt,实时后缀不宣称确定性。
  584. ## 能力矩阵
  585. | 模块 | 真实能力 | 解决的问题 |
  586. | --- | --- | --- |
  587. | Time Machine | Replay Bundle、Exact Replay、隔离 Worktree Fork、重复 Trial、Proof Hash | 复现非确定性行为并验证模型或 Prompt 变更 |
  588. | Runtime Governor | Provider Receipt、Context Capacity、Policy Engine、Run Compare | 用真实回执和执行证据治理容量、成本、缓存与失败 |
  589. | Causal Trace | LLM/Tool/Decision/Artifact DAG、关键路径、节点证据下钻 | 定位首个行为分歧和运行瓶颈 |
  590. | Evidence Delivery | Acceptance Contract、隔离 Builder、独立 Verifier、事务合并 | 让多 Agent 交付绑定可复验的 Git Tree 证据 |
  591. | Agent Loop | 流式对话、工具调用、最大轮次控制、行动说明 | 让模型真正进入可执行闭环 |
  592. | Local Tools | 文件读写、补丁、命令执行、用户确认 | 处理真实仓库和本地环境 |
  593. | MCP Runtime | 兼容 `.mcp.json`、stdio/HTTP server、动态发现工具 | 接入外部系统而不是只活在本地 |
  594. | Browser Automation | Chrome Bridge、DOM 扫描、点击、输入、等待、截图、OCR | 支撑真实 Web 工作流 |
  595. | Desktop Computer Use | macOS 权限检查、窗口激活、AX 控件树、受控点击、键盘、起草输入 | 让 Agent 能跨浏览器外的桌面界面行动 |
  596. | Context Manager | 工具结果压缩、消息组裁剪、session memory、full compact | 让长任务不被上下文拖死 |
  597. | Session Store | `meta.json`、`history.jsonl`、resume、local audit trail | 让任务可以中断后继续 |
  598. | SOP Runtime | SOP 索引、任务路由、工作 checkpoint | 把稳定流程固化成可复用约束 |
  599. | Skill Runtime | `skill install` 预览确认安装、`skill install --yes`、`skill install --dry-run`、`skill update --check`、`--pin` 版本锁定、`skill doctor`、manifest hash、`.cohort/skills`、`~/.cohort/skills`、`skill_read`、`/skill run`、`/<skill-alias>` | 像 Claude Code 一样安装、校验、锁定版本并按需加载可复用工作流 |
  600. | Evolution Memory | 证据约束、去重、项目记忆、审计日志 | 让“长期记忆”从摘要变成资产 |
  601. ## 一个完整任务是怎么跑起来的
  602. ```mermaid
  603. flowchart TD
  604. U[User Intent] --> R[CLI / REPL]
  605. R --> A[Agent Runner]
  606. A --> TM[Replay Recorder]
  607. A --> C[Context Manager]
  608. C --> G[Runtime Governor]
  609. C --> L[LLM Provider<br/>OpenAI-compatible / Anthropic]
  610. L --> A
  611. A --> T[Tool Registry]
  612. T --> F[File / Patch / Shell]
  613. T --> M[MCP Tools]
  614. T --> B[Browser Bridge]
  615. T --> D[Desktop Driver]
  616. T --> E[Memory Evolution]
  617. A --> S[Session Store]
  618. TM --> RB[Replay Bundle<br/>Hashes / Runtime / Frames]
  619. RB --> EX[Exact Replay]
  620. RB --> FK[Fork Replay<br/>Isolated Worktree]
  621. G --> DAG[Causal DAG / Policy / Compare]
  622. C --> SM[session memory.md]
  623. C --> CP[compact.md]
  624. C --> LM[relevant memory entries]
  625. E --> AUD[memory audit.jsonl]
  626. ```
  627. 从用户输入到最终结果,Cohort 实际做的是这几件事:
  628. 1. 读取当前 session、历史和上下文预算。
  629. 2. 把 relevant memory、session memory、compact 摘要按层注入请求。
  630. 3. 交给当前激活的 LLM provider 做工具调用决策。
  631. 4. 在受控工具层执行文件、Shell、浏览器、桌面或 MCP 操作。
  632. 5. 把执行证据和工具结果写回历史。
  633. 6. 在需要时压缩上下文、更新 checkpoint,或触发长期记忆写入流程。
  634. ## 为什么它不像玩具
  635. ### 1. 浏览器自动化不是截图脚本
  636. Cohort 通过本地 Browser Bridge 控制真实 Chrome:
  637. ```text
  638. ws://127.0.0.1:18777/browser
  639. ```
  640. 推荐流程是稳定的浏览器动作链,而不是“看一眼就点”:
  641. ```text
  642. open
  643. -> wait_for_load
  644. -> wait_for_stable
  645. -> snapshot / dom_summary
  646. -> click / type / press_key
  647. -> wait_for_selector / text / url
  648. -> verify
  649. ```
  650. 只有在 DOM 文本拿不到内容时,才降级到 `browser_ocr`。OCR 返回的是 `screenshot-local` bbox,不直接变成系统鼠标坐标。
  651. Chrome Bridge 需要加载本地扩展。npm 和 installer 都会准备扩展目录;用下面的命令查看路径或打开 Chrome 扩展页:
  652. ```bash
  653. cohort extension path
  654. cohort extension open
  655. ```
  656. 然后在 `chrome://extensions` 开启 Developer mode,点击 `Load unpacked`,选择 `cohort extension path` 输出的目录。
  657. ### 2. 桌面自动化不是任意乱点
  658. Cohort 当前的桌面能力基于 macOS Accessibility / AX,目标是做“受控的语义动作”,不是暴露一个危险的任意坐标点击器。
  659. ```text
  660. desktop_permissions
  661. -> desktop_windows
  662. -> desktop_activate
  663. -> desktop_ax_snapshot
  664. -> desktop_screenshot
  665. -> desktop_ocr
  666. -> desktop_ax_press
  667. -> desktop_ax_focus
  668. -> desktop_click
  669. -> desktop_visual_click
  670. -> desktop_press_key
  671. -> desktop_type_text
  672. ```
  673. 默认策略:
  674. - 优先 AX 控件树,只有 AX 不可用时才退到截图和 OCR。
  675. - `desktop_type_text` 只负责起草文本,不直接发送。
  676. - `desktop_press_key` 使用受限按键集合。
  677. - 高风险动作直接拒绝,外部副作用动作要求显式确认。
  678. ### 3. 长期记忆不是模型随手写便签
  679. 长期记忆遵循严格三步流程:
  680. ```text
  681. start_long_term_update
  682. -> memory_propose_update
  683. -> memory_apply_update
  684. ```
  685. 写入约束:
  686. - 必须引用已验证的工具证据。
  687. - 必须做去重和敏感信息过滤。
  688. - 成功写入前必须回读确认。
  689. - 每次 apply 都写审计记录。
  690. 这意味着 Cohort 的 memory 更像可追踪知识库,而不是一堆不可验证的 prompt summary。
  691. ### 4. 上下文不会失控
  692. 每次请求模型前,Cohort 会构造一个受控上下文窗口,而不是盲目把所有历史都拼进去。它会:
  693. - 清理协议非法的 orphan tool result。
  694. - 注入 relevant memory 和 session memory。
  695. - 注入 `compact.md` 作为长任务摘要。
  696. - 压缩旧工具结果,只保留头尾高价值片段。
  697. - 按消息组裁剪历史,避免拆坏 tool-call 协议对。
  698. session 目录结构:
  699. ```text
  700. temp/sessions/<session_id>/
  701. meta.json
  702. history.jsonl
  703. memory.md
  704. compact.md
  705. ```
  706. `history.jsonl` 始终是事实来源。压缩只影响发送给模型的请求副本,不改写原始历史。
  707. ## 系统架构
  708. | 层 | 目录 | 职责 |
  709. | --- | --- | --- |
  710. | App Assembly | `internal/app` | 配置加载、LLM client、工具注册、系统提示 |
  711. | Agent Runtime | `internal/agent` | 工具调用循环、运行日志、compact、证据收集 |
  712. | Replay Core | `internal/replay` | Replay Bundle、哈希校验、Exact Replay 和 Fork 前缀 |
  713. | Replay Execution | `internal/replayexec` | 隔离 Worktree Trial、实时后缀执行和实验报告 |
  714. | Runtime Evidence | `internal/traceview` | Provider 回执、容量治理、因果 DAG 和 Run Compare |
  715. | Control Plane | `internal/controlplane`, `internal/controlactions` | 本地安全会话、实体选择、Action 风险门禁和 Operation |
  716. | Evidence Delivery | `internal/delivery` | 契约、DAG Builder、证据、Verifier、审批与事务合并 |
  717. | Context Manager | `internal/contextmgr` | 请求构造、预算控制、裁剪、记忆注入 |
  718. | Tool Runtime | `internal/tools` | 文件、命令、浏览器、桌面、记忆和 checkpoint 工具 |
  719. | Browser Bridge | `internal/browser` | Chrome Bridge 的 WebSocket 协议与服务端实现 |
  720. | Desktop Driver | `internal/desktop` | macOS helper 的 Go 接口与 runner |
  721. | Session Store | `internal/session` | session 列表、恢复、历史与元数据 |
  722. | LLM Client | `internal/llm` | OpenAI-compatible Chat Completions + Anthropic Messages API client |
  723. | MCP | `internal/mcp` | server 管理、权限缓存、配置持久化 |
  724. | REPL / CLI | `internal/repl`, `internal/cli` | 交互式 shell、slash 命令、CLI 入口 |
  725. | Verified Memory | `internal/evolution` | 记忆校验、apply、审计 |
  726. ## CLI 与交互命令
  727. ### 外部 CLI
  728. ```bash
  729. cohort # 进入交互模式
  730. cohort ask "task" # 执行一次任务后退出
  731. cohort tools # 查看已挂载工具
  732. cohort config # 查看有效配置
  733. cohort ui # 打开本地 Control Center
  734. cohort trace graph last --open # 查看最近一次运行的因果 DAG
  735. cohort trace replay exact ... # 离线校验 Replay Bundle
  736. cohort trace replay fork ... # 在隔离 Worktree 中运行分叉实验
  737. cohort mcp list # 查看 MCP server
  738. cohort mcp status # 检查 MCP server 连通性
  739. cohort mcp add <name> -- ... # 添加 stdio MCP server
  740. cohort mcp tools <name> # 查看 server 提供的工具
  741. cohort mcp probe <name> # 探测 server 可用性
  742. cohort mcp remove <name> # 删除 MCP server
  743. cohort session list # 查看本地 session
  744. cohort session resume <id> # 恢复 session
  745. ```
  746. ### 交互模式 Slash Commands
  747. ```text
  748. /help
  749. /model
  750. /config
  751. /tools
  752. /session
  753. /session list
  754. /session memory
  755. /resume <session_id>
  756. /compact
  757. /full-compact
  758. /memory
  759. /sop candidates
  760. /sop promote <id>
  761. /clear
  762. /exit
  763. ```
  764. <details>
  765. <summary>当前注册工具</summary>
  766. ```text
  767. file_read
  768. file_write
  769. file_patch
  770. code_run
  771. ask_user
  772. update_working_checkpoint
  773. start_long_term_update
  774. memory_propose_update
  775. memory_apply_update
  776. browser_tabs
  777. browser_open
  778. browser_scan
  779. browser_dom_summary
  780. browser_execute_js
  781. browser_click
  782. browser_click_element
  783. browser_type
  784. browser_type_element
  785. browser_press_key
  786. browser_snapshot
  787. browser_wait_for_load
  788. browser_wait_for_selector
  789. browser_wait_for_text
  790. browser_wait_for_url
  791. browser_wait_for_stable
  792. browser_screenshot
  793. browser_ocr
  794. desktop_permissions
  795. desktop_windows
  796. desktop_activate
  797. desktop_screenshot
  798. desktop_ax_snapshot
  799. desktop_ocr
  800. desktop_ax_press
  801. desktop_ax_focus
  802. desktop_click
  803. desktop_visual_click
  804. desktop_press_key
  805. desktop_type_text
  806. computer_see
  807. computer_find
  808. computer_click
  809. computer_double_click
  810. computer_right_click
  811. computer_type
  812. computer_press
  813. computer_wait
  814. computer_check
  815. computer_scroll
  816. computer_drag
  817. computer_drop
  818. computer_clipboard_write
  819. computer_paste
  820. computer_window_switch
  821. computer_menu
  822. computer_file_dialog
  823. computer_window_move
  824. computer_window_resize
  825. computer_visual_snapshot
  826. computer_execute_step
  827. computer_execute_plan
  828. ```
  829. </details>
  830. ## 安全模型
  831. 自动化如果没有边界,最终一定会变成事故放大器。Cohort 的策略是把风险前置到 runtime,而不是把判断完全留给模型。
  832. 风险分级:
  833. - `R1` 可恢复动作:允许直接执行,例如展开、切换、菜单、Tab 导航。
  834. - `R2` 外部副作用:必须通过 `ask_user` 获得一次性确认令牌,例如发送、提交、上传、保存、发布。
  835. - `R3` 高风险动作:直接拒绝,例如支付、审批、授权、删除、登录验证。
  836. 这套规则同时作用在浏览器、桌面和需要副作用确认的执行链路上。
  837. ## 配置
  838. 推荐配置使用 `active_profile + profiles`。下面是一份可直接扩展的多模型配置:
  839. ```yaml
  840. language: zh
  841. workspace: ./workspace
  842. log_dir: ./temp/model_responses
  843. max_turns: 300
  844. llm:
  845. active_profile: deepseek
  846. fallback_profiles: [local]
  847. profiles:
  848. deepseek:
  849. provider: openai
  850. name: deepseek
  851. api_key: ${DEEPSEEK_API_KEY}
  852. api_base: https://api.deepseek.com
  853. model: deepseek-v4-pro
  854. stream: true
  855. connect_timeout_seconds: 10
  856. read_timeout_seconds: 120
  857. max_retries: 2
  858. local:
  859. provider: openai
  860. name: local
  861. api_key: ${LOCAL_OPENAI_API_KEY}
  862. api_base: http://127.0.0.1:11434/v1
  863. model: qwen3-coder
  864. stream: true
  865. connect_timeout_seconds: 10
  866. read_timeout_seconds: 120
  867. max_retries: 1
  868. claude:
  869. provider: anthropic
  870. name: claude
  871. api_key: ${ANTHROPIC_API_KEY}
  872. api_base: https://api.anthropic.com
  873. model: claude-3-5-sonnet-latest
  874. stream: true
  875. connect_timeout_seconds: 10
  876. read_timeout_seconds: 120
  877. max_retries: 2
  878. context:
  879. max_history_messages: 40
  880. keep_recent_tool_results: 2
  881. max_tool_result_chars: 12000
  882. compacted_tool_head_chars: 4000
  883. compacted_tool_tail_chars: 4000
  884. max_request_chars: 100000
  885. max_session_memory_chars: 20000
  886. max_compact_summary_chars: 60000
  887. enable_micro_compact: true
  888. ```
  889. 配置文件查找顺序:
  890. 1. `--config <file>` 或 `-c <file>`
  891. 2. `COHORT_CONFIG`
  892. 3. 当前目录的 `configs/config.yaml`
  893. 4. `~/.cohort/config.yaml`
  894. API key 推荐使用环境变量注入,不要写死在配置文件里。运行 `cohort config` 可以查看当前激活 profile、模型、上下文窗口和 key 是否已设置;运行 `cohort doctor` 可以做启动前诊断。
  895. ## 项目结构
  896. ```text
  897. cmd/cohort/ CLI 入口
  898. configs/ 本地配置
  899. docs/ 使用教程、技术设计、开发记录
  900. assert/ 浏览器 bridge 扩展资源
  901. internal/app/ 应用装配与系统提示
  902. internal/agent/ Agent loop、证据流、compact
  903. internal/browser/ Chrome Bridge 协议与服务
  904. internal/cli/ 命令分发和 CLI 子命令
  905. internal/contextmgr/ 请求构造、裁剪、记忆注入
  906. internal/controlplane/ 本地安全控制面与 Operation
  907. internal/delivery/ 证据驱动的多 Agent 交付
  908. internal/desktop/ 桌面驱动与 helper runner
  909. internal/evolution/ 长期记忆演化与审计
  910. internal/llm/ OpenAI-compatible + Anthropic client
  911. internal/mcp/ MCP server 管理
  912. internal/replay/ Replay Bundle、Exact/Fork Replay
  913. internal/replayexec/ 隔离 Worktree 分叉实验
  914. internal/repl/ 交互 shell 和 slash 命令
  915. internal/session/ session 存储与恢复
  916. internal/tools/ 全部受控工具
  917. internal/traceview/ 因果 DAG、容量与基线对比
  918. sops/ SOP 索引和执行手册
  919. workspace/ 默认工作区与长期记忆目录
  920. temp/ session、日志和运行时输出
  921. ```
  922. ## 文档索引
  923. - [CHANGELOG.md](CHANGELOG.md): 版本变更与已知限制
  924. - [SECURITY.md](SECURITY.md): 安全边界、漏洞报告和加固建议
  925. - [docs/usage.md](docs/usage.md): 使用方法、命令、session 恢复
  926. - [docs/cohort_time_machine.md](docs/cohort_time_machine.md): 可验证录制、Exact Replay、Fork Replay 与确定性边界
  927. - [docs/proof_carrying_runtime_governor.md](docs/proof_carrying_runtime_governor.md): Provider 回执、上下文容量、策略干预与 Run Compare
  928. - [docs/causal_trace_graph.md](docs/causal_trace_graph.md): 因果 DAG、关键路径与执行证据下钻
  929. - [docs/evidence_driven_multi_agent_delivery.md](docs/evidence_driven_multi_agent_delivery.md): 证据驱动的多 Agent 交付与事务合并
  930. - [docs/context_management_design.md](docs/context_management_design.md): 上下文裁剪与 compact 设计
  931. - [docs/browser_operation_design.md](docs/browser_operation_design.md): 浏览器操作设计
  932. - [docs/desktop_computer_use_technical_design.md](docs/desktop_computer_use_technical_design.md): 桌面 Computer Use 技术设计
  933. - [docs/cohort_mcp_integration_design.md](docs/cohort_mcp_integration_design.md): MCP 集成设计
  934. - [docs/cohort_self_evolution_research.md](docs/cohort_self_evolution_research.md): 自演化与记忆方向研究
  935. - [docs/capability_evolution_technical_design.md](docs/capability_evolution_technical_design.md): 能力边界拓展、依赖安装、Skill/Tool 生成与验证闭环方案
  936. - [docs/agent_observability_technical_design.md](docs/agent_observability_technical_design.md): Agent 可观测性、tracing 和调优方案
  937. ## 开发与测试
  938. ### 本地开发
  939. ```bash
  940. go run . config
  941. go run . tools
  942. go run . ask "读取 configs/config.yaml 并解释关键字段"
  943. ```
  944. ### 测试
  945. ```bash
  946. ./internal/tests/run.sh
  947. go vet ./...
  948. ```
  949. 如果只想跑某一类测试:
  950. ```bash
  951. ./internal/tests/run.sh -run TestDesktop -count=1
  952. ```
  953. ## 设计原则
  954. - 本地优先:执行、日志、历史、会话、截图、记忆默认留在本地。
  955. - 工具优先:让模型负责推理,让 runtime 负责约束和执行。
  956. - 历史不可变:即使上下文被压缩,`history.jsonl` 仍然保留完整事实。
  957. - 上下文分层:recent history、session memory、compact、relevant memory 各司其职。
  958. - 记忆可验证:没有工具证据的“经验”不能直接进入长期记忆。
  959. - 渐进演化:先把单 Agent runtime 做稳,再考虑更重的编排、UI 和生态。
  960. ## 非目标
  961. 为了让边界更清楚,下面这些不是 Cohort 当前要解决的问题:
  962. - 不是云端托管 Agent 平台。
  963. - 不是无约束的自动点击机器人。
  964. - 不是“所有信息都塞进 prompt”的长上下文捷径。
  965. - 不是靠模型自由发挥写记忆的黑盒系统。
  966. ## 结语
  967. 如果你想做的是一个真正能落地的本地 Agent 系统,而不是一个只会说“我可以帮你”的聊天界面,Cohort 的重点就在这里:
  968. - 有执行闭环。
  969. - 有上下文治理。
  970. - 有审计和恢复。
  971. - 有可以进化但不失控的记忆体系。
  972. 这正是它和普通 Agent Demo 拉开差距的地方。
  973. ## Skill 系统
  974. Cohort 的 Skill 是可安装、可发现、可按需读取的工作流包。启动时只把 Skill 摘要注入系统提示词;真正命中任务后,模型再通过 `skill_read` 读取完整 `SKILL.md`。
  975. 常用命令:
  976. ```bash
  977. go run . skill install ./path/to/skill
  978. go run . skill install --yes ./path/to/skill
  979. go run . skill install --dry-run ./path/to/skill
  980. go run . skill install --pin v1.2.3 https://example.com/org/skill-repo.git
  981. go run . skill doctor project/<skill_name>
  982. go run . skill update --check project/<skill_name>
  983. go run . skill update --pin v1.2.4 project/<skill_name>
  984. go run . skill update project/<skill_name>
  985. go run . skill uninstall project/<skill_name>
  986. go run . skill list
  987. ```
  988. `skill install` 默认会先解析来源、定位 `SKILL.md`、计算文件数、内容 SHA256 和 `requires` 依赖摘要,并展示候选 `SKILL.md` 指令内容,然后提示确认;确认后才写入 `.cohort/skills`。这一步的安全边界是让用户在安装前看到“即将允许 Agent 读取并遵循的指令”,同时确认来源、commit、目标目录、覆盖行为和依赖声明。它不是自动安全审计器,不会替用户判断第三方 Skill 是否可信。
  989. `--yes` 用于脚本或自动化场景,表示预览后直接安装;`--dry-run` 只预览不安装。正式安装会写入 `.cohort-skill.json`,记录 `source`、`source_type`、`source_ref`、`requested_ref`、`resolved_ref`、`pinned`、`scope`、`alias`、`installed_at` 和 `content_hash`。`--pin <git-ref>` 会把 git Skill 锁到解析后的 commit;后续不带参数的 `skill update` 和 `skill update --check` 会继续使用这个 commit,除非再次传 `--pin <new-ref>`。`skill doctor` 会检查路径边界、Skill 正文、manifest、hash 漂移和 `requires` 声明的 MCP/env/commands 依赖,适合在更新或手工编辑后做健康检查。
  990. Skill 可以在 `SKILL.md` frontmatter 中声明运行前依赖。Cohort 只解析、展示和诊断这些依赖,不会自动安装命令、添加 MCP Server、申请授权或输出环境变量值。
  991. ```yaml
  992. ---
  993. name: lark-doc-helper
  994. description: Work with Lark documents.
  995. requires:
  996. mcp:
  997. - lark
  998. env:
  999. - LARK_APP_ID
  1000. - LARK_APP_SECRET
  1001. commands:
  1002. - npx
  1003. ---
  1004. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.