# NoClaw — 让你的 Obsidian 拥有会成长的 AI Agent

<p align="center">
  <strong>多引擎 · 有记忆 · 会沉淀 · 可进化</strong>
</p>

<p align="center">
  [ <a href="README.md">English</a> | <a href="README_ZH.md">简体中文</a> ]
</p>

## 概览

NoClaw 把 Claude Code、Codex、Gemini CLI、OpenCode、Qwen Code、Kimi Code 等引擎接进 Obsidian。你可以为不同 Agent 分配不同引擎，让它们读取当前笔记、继续会话、执行任务、整理知识、积累记忆。

NoClaw 不只是聊天侧边栏。它会把有价值的上下文、记忆、知识笔记和工作流留在你的 Vault 里；底层引擎可以随时切换，沉淀下来的东西仍然是普通 Markdown。

<p align="center">
  <img src="docs/assets/noclaw-screenshot.gif" alt="NoClaw demo" width="860">
</p>

## 核心理念

- **多引擎，不锁定**：Agent 与引擎解耦。你可以为同一个 Agent 分配 Claude Code、Codex、Gemini CLI、OpenCode 或自定义 ACP CLI。
- **知识库即 Agent**：Agent 的身份、个人画像、记忆、Wiki 与技能都保存在 Vault 中，不需要迁移到外部数据库。
- **纯文本优先**：工作区、记忆日志、知识笔记和技能文件都使用 Markdown 或 JSONL 等可读格式。
- **本地优先**：NoClaw 不做遥测。除非你配置并调用对应 AI 引擎，否则 Vault 数据不会离开本机。

## 架构

```text
Agent（用户定义的 AI 人格）
  ├─ 身份、记忆、技能、Wiki（Vault 中的纯文本工作区）
  └─ 引擎映射（主引擎 + 备用链）
         │
         ▼
NoClaw（Hook 流水线 + 权限护栏 + 知识检索）
         │
         ▼
引擎 CLI（Claude Code / Codex / Gemini CLI / OpenCode / Qwen Code / Kimi Code / 自定义）
         │
         ▼
LLM API（Anthropic / OpenAI / Google / 阿里 / Moonshot / 用户配置端点）
```

## 功能特性

### 多引擎 Agent 平台

- **ACP 原生通信**：通过 Agent Client Protocol 连接 CLI 引擎，并支持任意兼容 ACP 的自定义引擎。
- **Agent 与引擎解耦**：一个 Agent 可分配多个引擎，列表中的第一个作为默认引擎。
- **并发会话**：支持多个聊天视图、浮动窗口和按 Agent 隔离的会话队列。
- **命令面板集成**：可直接打开聊天、为指定引擎新建聊天、批准或拒绝权限请求、广播提示词。
- **桌面端自动检测**：启动时会检测常见 CLI 路径，只填充空配置，不覆盖已有设置。

### Obsidian 原生上下文

- **自动提及当前笔记**：默认将当前活动笔记纳入消息上下文。
- **`@[[笔记名]]` 引用**：在聊天中直接引用 Vault 笔记。
- **上下文压缩**：工具结果剪枝、记忆刷新、检查点和归档机制帮助长会话保持在 token 预算内。
- **会话管理**：创建、恢复、派生、导出会话，并保留本地会话元数据。

### 知识与记忆

- **自动知识沉淀（可选）**：会话结束后可自动生成带反馈链接的原子笔记。
- **局部图谱展开**：通过 Obsidian 链接关系提取相关上下文，不依赖向量数据库。
- **主权记忆**：Agent 记忆写入可审计的 `LEDGER.md`，再物化为 `USER.md` 与 `MEMORY.md`。
- **热更新 Wiki 规则**：每个 Agent 可通过 `WIKI_CONFIG.md` 调整知识沉淀路径和规则。

### 进化与自动化

- **SOP 自动结晶（实验性，可选）**：复杂成功会话可提取为可复用的标准操作程序。
- **Nudge 引擎（实验性，可选）**：空闲时后台审查记忆质量并建议技能修补。
- **Cron 任务**：可创建周期性 AI 任务，用独立会话执行维护、总结等工作。
- **聊天频道（可选）**：通过自托管的 `@yungho/noclaw-channel` 桥接微信等外部消息入口。

### 安全护栏

- **内容安全扫描**：对提示注入、密钥泄露和危险记忆操作进行拦截。
- **MCP Bridge 安全层**：工具定义扫描、响应内容检查和权限门控用于降低不可信 MCP 工具风险。
- **权限请求可控**：敏感操作可以由用户逐次批准，也可在明确理解风险后启用自动允许。

## 安装

### 通过 BRAT（推荐）

1. 在 Obsidian 中安装并启用 [BRAT](https://tfthacker.com/Obsidian42-B-Repo-Auto-Installer/)。
2. 运行 `BRAT: Add a beta plugin for Obsidian`。
3. 粘贴仓库地址：`https://github.com/Yungho/obsidian-noclaw`。
4. 安装后在 设置 → 社区插件 中启用 NoClaw。

### 手动安装

1. 从 [GitHub Releases](https://github.com/Yungho/obsidian-noclaw/releases) 下载最新版。
2. 将 `main.js`、`manifest.json`、`styles.css` 放入 `.obsidian/plugins/noclaw/`。
3. 重启 Obsidian，进入 设置 → 社区插件，启用 NoClaw。

## 快速开始

### 1. 安装至少一个 CLI 引擎

以 OpenCode 为例：

```bash
curl -fsSL https://opencode.ai/install | bash
# 或者使用 npm 安装:
npm install -g opencode-ai
```

OpenCode 默认参数为 `acp`。Gemini CLI 和 Qwen Code 默认使用 `--acp`。Codex 可使用 `codex` 或 `codex-acp`，Claude Code 可使用 `claude-agent-acp`、`claude-code-acp` 或 `claude`。

### 2. 配置提供商

1. 打开 设置 → NoClaw → 提供商。
2. 找到对应引擎，填写 API Key、命令路径、参数和环境变量。
3. 可点击自动检测按钮让 NoClaw 填入已安装 CLI 的路径。

常用查找命令：

```bash
which opencode
which codex
which gemini
which claude-agent-acp
```

### 3. 创建 Agent

1. 打开 设置 → NoClaw → 智能体。
2. 点击 创建 Agent。
3. 填写名称、角色和风格，并分配一个或多个引擎。
4. 点击功能区 NoClaw 图标，或从命令面板运行 `Open chat`。

### 4. 定制工作区

Agent 工作区位于默认的 `noclaw/workspace-<id>/`。常见文件包括：

- `IDENTITY.md`：Agent 身份、角色和风格。
- `USER.md`：用户画像和偏好。
- `memory/LEDGER.md`：可审计的记忆事件日志。
- `memory/MEMORY.md`：物化后的长期记忆视图。
- `WIKI_CONFIG.md`：知识沉淀配置（如果存在）。
- `wiki/`：自动沉淀的原子知识笔记。

## 系统要求

- Obsidian **1.11.4** 或更高版本。
- 仅桌面端：`isDesktopOnly: true`。
- 至少一个可用 CLI 引擎：Claude Code、Codex、Gemini CLI、OpenCode、Qwen Code、Kimi Code 或兼容 ACP 的自定义引擎。

## 平台支持

NoClaw 当前只支持桌面端。移动端不作为直接运行目标，因为 Obsidian 移动端无法启动本地 CLI 进程，后台执行和流式响应能力也受平台限制。

移动端可通过聊天频道间接使用：桌面端 Obsidian 保持运行，自托管桥接服务接收外部消息，再由 NoClaw 处理。

## 隐私与网络

NoClaw 不收集遥测、崩溃报告或使用分析。它只在以下场景发生网络通信：

| 场景 | 连接目标 | 发送内容 |
|---|---|---|
| Claude Code | Anthropic API | 当前会话消息、工具结果、Agent 指令 |
| Codex / OpenCode | OpenAI 或用户配置端点 | 当前会话消息、工具结果、Agent 指令 |
| Gemini CLI | Google API | 当前会话消息、工具结果、Agent 指令 |
| Qwen Code / Kimi Code | 用户配置端点 | 当前会话消息、工具结果、Agent 指令 |
| Chat Channels | 你的自托管桥接服务 | 外部频道消息和 Agent 回复 |

Vault 文件不会被整库上传。只有当前会话内容、工具结果，以及你明确通过 `@[[笔记名]]` 或自动提及纳入的笔记内容会进入对应引擎上下文。

API Key 存储方式取决于当前配置：专用 API Key 字段会通过 Obsidian `secretStorage` 保存；环境变量文本框中的 `KEY=VALUE` 会按设置内容保存，请只放入你愿意保存在插件配置中的值。

## 路线图

- ✅ **核心净化**：AgentLoop Hook 流水线、EventBus、ServiceContainer、MCP 安全层、plugin.ts 拆分。
- ✅ **知识觉醒**：自动知识沉淀、局部图谱展开、ContentScanner、持久化队列。
- 🟡 **自我进化**：SOP 自动结晶、Nudge 引擎、记忆质量审查和技能修补。
- ⏳ **SubAgent 编排**：Orchestrator-Subagent 模式、SubAgent 会话记录、并行任务分发。

## 贡献

欢迎提交 issue、PR 和复现步骤。开发前请阅读 `CONTRIBUTING.md`，并优先运行：

```bash
npm run lint
npm run test
npm run build
```

## 许可证

MIT — 详见 [LICENSE](LICENSE)。