# owncoder

**Repository Path**: f6688/owncoder

## Basic Information

- **Project Name**: owncoder
- **Description**: 一个注重安全的AI编码工具，可以对密码密钥自动脱敏，保护隐私。不会私自上传任何代码，所有索引都在本地，向量搜索也在本地。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-20
- **Last Updated**: 2026-10-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OwnCoder

English: [README_EN.md](./README_EN.md) ｜ 官网：[https://www.owncoder.cn](https://www.owncoder.cn)

**用 AI 写代码，担心泄密？Token 烧钱？**

**OwnCoder：本地脱敏 + 高能力模型规划 + 高性价比模型执行，安全与成本兼得。**

---

## 🎯 两个开发者痛点，一次解决

你是否遇到过这些问题？

- 配置文件包含数据库密码和 API Key，不敢直接交给模型处理
- 复杂任务反复读取代码、修改文件和运行测试，全程使用高成本模型费用很高
- 代码包含公司内部域名、私钥等敏感信息，担心被模型服务记录

**OwnCoder 的解决方案：**

| 核心价值 | 怎么实现 | 实际效果 |
|----------|----------|----------|
| **🔒 安全优先：本地脱敏** | 读取受保护文件时，先在本地掩码敏感值（如 `API_KEY=***`），再交给模型；支持 60+ 内置规则和自定义规则 | `.env`、私钥、凭证文件自动保护；**不改写原文件，敏感明文不发送** |
| **💰 降低成本：模型分工** | 高能力模型负责理解和规划，高性价比模型根据计划执行；结合按需检索和上下文缓存 | 将消耗大量 Token 的执行循环交给成本更低的模型 |

---

## 🔒 安全防护：三层脱敏 + 本地处理

### 为什么需要文件脱敏？

使用远程 AI 模型时，完成任务所需的代码片段和上下文会发送给模型服务。**OwnCoder 会在发送前于本地掩码规则覆盖的敏感信息**，让你在使用 AI 提升效率的同时降低密钥泄露风险。

### 三层防护

| 防护层级 | 工作原理 | 覆盖范围 |
|----------|----------|----------|
| **📁 文件名匹配** | 60+ 内置 glob 模式识别敏感文件 | `.env`、`*credentials*`、`*.pem`、`*.key`、`kubeconfig`、`terraform.tfvars` 等 |
| **🔑 格式识别** | 25+ 种已知密钥格式的精确正则 | 常见服务密钥、数据库连接串、JWT、PEM 私钥块等 |
| **🏷️ 关键词匹配** | 通用凭证关键词和大写环境变量后缀 | `password`、`secret`、`token`、`api_key`、`*_PASSWORD`、`*_SECRET`、`*_TOKEN` 等 |

### 两种脱敏粒度

- **值级脱敏**（`.env`、`credentials.json` 等）：只掩码敏感字段的值，其余内容保持可读，方便 Agent 理解文件结构。
- **全文件脱敏**（`*.pem`、`*.key`、`id_rsa`、`*.sqlite` 等）：掩码非空行内容；部分键值行保留键名和分隔符，以便理解结构。

**效果示例：**

```bash
# 原始 .env 文件
DATABASE_URL=postgresql://user:pass123@db.internal.com/prod
SERVICE_API_KEY=secret-value
LOG_LEVEL=info

# 值级脱敏后
DATABASE_URL=***
SERVICE_API_KEY=***
LOG_LEVEL=info
```

> **适用范围：**值级检测规则只用于内置规则覆盖的敏感文件，普通源代码文件不会自动执行这些检测。自定义敏感文件规则采用全文件脱敏；`.env.example`、`.env.sample` 等模板文件在允许列表中，不参与脱敏。请通过预览确认项目中的敏感文件已被规则覆盖。

### 自定义规则：适配你的项目

在 **设置 → 安全** 中，你可以：

**1. 添加自定义敏感文件（glob 模式）**

```text
config/production.json
*.secret
my-custom-env.*
internal/keys/*
```

**2. 添加自定义检测规则（正则表达式）**

```text
INTERNAL-\d{8}-[A-Z]+
my_company_[A-Za-z0-9]{32}
corp-secret:\s*\S+
```

**3. 测试脱敏预览**

选择任意本地文件，系统会使用当前规则运行脱敏引擎并展示：

- 匹配了哪些规则
- 每种规则命中了几处
- 脱敏后的内容预览

**无需调用模型，即可在本地验证脱敏效果。**

### 其他安全措施

- **本地处理**：文件脱敏、代码索引和检索在本地完成；脱敏不会修改磁盘上的原文件。
- **工作区边界保护**：Agent 只能修改工作区内的文件。
- **危险命令确认**：`rm -rf`、`git push --force`、`chmod 777` 等操作会触发确认；**按 Enter 不会放行**，必须手动点击“允许”。窗口崩溃或 120 秒无响应时会**自动拒绝**（fail-closed）。

---

## 💰 省 Token：高能力模型规划，高性价比模型执行

### 为什么模型分工能降低成本？

传统方式常让高成本模型同时承担规划和多轮执行。OwnCoder 将工作拆成两个阶段：

1. **规划阶段**：高能力模型理解意图、整理约束并生成有顺序的执行步骤。
2. **执行阶段**：高性价比模型按计划读取代码、修改文件、运行测试并修复问题。

执行阶段通常包含更多工具调用和反馈循环。将它交给成本更低的模型，可以降低大量执行 Token 的单价，同时让高能力模型专注于关键决策。

```text
用户需求
  ↓
高能力模型：理解意图 → 拆解任务 → 给出执行步骤
  ↓
高性价比模型：读取代码 → 修改文件 → 运行测试 → 修复问题
  ↓
验证通过 → 交付
```

### 配置方式

| 阶段 | 推荐模型 | 负责的工作 |
|------|----------|------------|
| **任务分解** | 推理和规划能力更强的模型 | 理解需求、整理约束、生成有顺序的步骤 |
| **循环执行** | 编码可靠、使用成本更低的模型 | 按计划检索代码、编辑文件、执行命令和检查结果 |

1. 在 **设置 → 模型** 中添加所需模型。
2. 进入 **设置 → 常规**，勾选 **执行阶段单独配置**。
3. 开启后，即可分别配置 **任务分解阶段** 和 **执行阶段** 使用的模型：任务分解阶段选择规划能力更强的模型，执行阶段选择适合编码执行的模型。

> 实际节省取决于任务复杂度、模型能力和服务商定价。

### 更多 Token 优化手段

#### 1. 提示词结构优化：最大化缓存命中率

**原理**：许多模型服务商支持提示缓存（Prompt Cache），对重复出现的输入 Token 按更低价格计费。OwnCoder 的提示词拼接策略专门针对缓存优化设计。

**实现方式**：
- **不变内容前置**：系统提示词（含工具定义）、平台信息、项目规则等固定内容放在消息序列前部
- **变动内容后置**：用户输入、任务分解结果、当前会话等动态内容放在后部
- **字节级稳定性**：固定部分的拼接顺序和格式保持严格一致，确保跨轮次的缓存前缀完全匹配

**代码位置**：
```
packages/core/src/harness/loop/context.ts (buildInitialContext)
  1. systemPrompt (系统提示词 + 工具定义)
  2. platformInfo (平台信息：操作系统、路径分隔符)
  3. projectContext (项目规则、技术栈、项目大小)
  4. userMessage (用户输入 - 每轮变化)
  5. taskDecompose (任务分解结果 - 每轮变化)
```

**效果**：系统提示词和工具定义自动享受缓存；重复的项目上下文命中率可达 60-80%。下图记录了一次约 95% 的缓存命中情况（按 缓存 Token ÷（输入 Token + 输出 Token）计算，分母包含输出 Token），仅作为使用示例；实际命中率会随模型服务、上下文和任务变化。

![上下文缓存命中示例](%E5%B1%8F%E5%B9%95%E6%88%AA%E5%9B%BE%202026-09-17%20235326.png)

#### 2. 双模型分工：规划与执行解耦

**原理**：任务分解阶段消耗的 Token 较少但需要强规划能力；执行阶段包含大量工具调用和迭代但对推理要求相对较低。

**配置方式**：
- 在 **设置 → 常规** 中勾选 **执行阶段单独配置**
- **任务分解模型**：选择推理能力强的模型（如 GPT-4、Claude 3.5 Sonnet）
- **执行阶段模型**：选择编码可靠、价格更低的模型（如 GPT-4o-mini、Claude 3.5 Haiku）

**实现位置**：
```
packages/core/src/harness/loop/stages.ts (resolveStageModel)
  - stageType === "react" 时使用 workflow.harness.reactModel
  - 其他阶段（含 task_decompose）使用 workflow 默认模型
```

**预期收益**：执行阶段通常占据 70-80% 的 Token 消耗，将其交给成本更低的模型可显著降低总费用。

#### 3. 零叙事工具调用：输出即成本

**原理**：LLM 服务按输出 Token 计费，且输出价格通常是输入的 2-3 倍。减少模型的"解释性文字"，让模型直接调用工具完成任务，可以大幅降低输出成本。

**提示词规则**（位于 `packages/settings/src/builtin-prompts.ts`）：
```
## Key Rule: Zero-Narrative Tool Calls
By default, call tools directly to complete the task. Output no text other than tool calls.

Forbidden outputs:
- Transitional phrases, planning narration, progress commentary, greetings, explanations.
- "Let me first...", "Now I'll start...", "Next...", "I'll search...", "First I need..."
- Any explanatory text between tool calls.

Requirements:
- When action is needed, call a tool immediately.
- Zero text between tool calls.
- Do not restate tool results unless reporting final results.
```

**执行纪律**：
- ❌ 错误：`"我现在开始修改文件..."` [然后调用工具]
- ✅ 正确：`[直接调用 apply_patch 工具]`

**实际效果**：模型只在需要用户决策或报告最终结果时输出文字，中间执行过程全部使用工具调用。对于多步骤任务，输出 Token 可降低 60-80%。

#### 4. 其他优化措施

- **按需读取代码**：使用符号搜索、文件大纲和局部读取提供相关代码，减少整文件进入上下文。
- **复用相关历史**：检索与当前任务相关的历史，减少重复提供背景和重复探索。

---

## 核心功能

### 🧠 Plan + Agent 双模式

| 模式 | 能力 | 适用场景 |
|------|------|----------|
| **Plan** | 只读：分析代码、搜索、生成方案 | 需求分析、架构设计、代码审查 |
| **Agent** | 读写：编辑文件、执行命令、运行测试 | 功能开发、Bug 修复、重构 |

### 🧪 执行级验证引擎

Agent 修改代码后，会自动运行真实的编译器、类型检查器或测试：

- 类型检查：`tsc`、`mypy`、`go vet`
- 代码检查：`eslint`、`ruff`、`pylint`
- 测试运行：自动发现关联测试文件

验证失败时进入**自动修复循环**，根据错误信息继续修正。

### 📝 内联变更审查

每次 Agent 操作后，对话上方会显示变更栏和逐文件 diff：

- 独立“保留”与“撤销”按钮
- “全部保留”与“全部撤销”全局操作
- 点击文件名可在 Monaco 编辑器中打开

### 📦 嵌入式代码检索

- **统一索引系统**：基于 SQLite + FTS5 的高性能全文索引
  - 符号搜索：通过 tree-sitter 支持 35+ 种语言
  - 全文检索：FTS5 虚拟表提供快速关键词搜索
  - 经验索引：存储故障修复记录，支持跨会话复用
  - 增量扫描：智能更新并遵循 `.gitignore`
- **本地 RAG 嵌入**：提供多种后端，可离线使用

### 🧩 其他亮点

- **MCP 协议**：配置任意 stdio MCP 服务器，工具自动提供给 Agent
- **子 Agent 协调**：层级任务分解，子 Agent 间通信并共享记忆
- **经验学习**：记录以往修复模式，支持跨会话检索
- **@ 文件提及**：使用 `@文件名` 提供上下文，支持自动补全
- **多会话并发**：同时运行多个 Agent 任务
- **双语设计**：中文界面和英文运行时提示词，面向中文开发者

---

## 快速开始

### 前置要求

- **Node.js** >= 20
- **pnpm**（`npm install -g pnpm`）
- **Windows**（当前主要支持的平台）

> `.npmrc` 已配置 npmmirror 镜像以加速下载。

### 安装与运行

```bash
git clone https://github.com/YOUR_ORG/owncoder.git
cd owncoder
pnpm install

# 为 Electron 重建原生模块（better-sqlite3、node-pty）
cd apps/desktop
pnpm rebuild
cd ../..

# 构建所有 TypeScript 包
pnpm -r run build

# 启动开发服务器
pnpm dev
```

> **为什么需要 `pnpm rebuild`？** `better-sqlite3` 和 `node-pty` 是 C++ 原生模块，需要针对 Electron 的 Node.js 版本编译。跳过此步骤会在运行时出现 `NODE_MODULE_VERSION` 不匹配。每次执行 `pnpm install` 后都需要重新运行。

### 连接大模型

OwnCoder 支持 OpenAI 兼容接口：

1. 打开 **设置 → 模型**。
2. 添加服务商，填写名称、Base URL 和 API Key。
3. 在对话栏下拉菜单中选择模型。

可连接任何提供 OpenAI Chat Completions 兼容 API 的服务。

---

## 🛠️ 开发

### 项目结构

| 路径 | 说明 |
|------|------|
| `apps/desktop` | Electron 桌面应用 |
| `packages/shared` | 共享类型 |
| `packages/settings` | 配置 schema、流水线节点、脱敏规则 |
| `packages/llm` | OpenAI 兼容客户端 |
| `packages/core` | Agent 框架核心（循环、补丁、检查点、验证、LSP、RAG、脱敏引擎） |
| `packages/index` | 统一索引系统（SQLite + FTS5，纯 TypeScript 实现） |
| `scripts/` | 冒烟测试和构建脚本 |

---

## 📊 用户统计

本项目使用以下脚本进行用户统计：

```html
<script async src="https://01a0aa89-d212-7984-96e9-45fa2ee539c2.spst2.com/ustat.js"></script>
```

---

## 📄 许可协议

本项目采用 **PolyForm Noncommercial License 1.0.0**，完整协议见 [LICENSE](./LICENSE)。

**简单来说：**

- ✅ 可用于个人、学术、教育和非营利目的
- ✅ 可在非商业用途下使用、修改和分发本项目
- ❌ **不允许商业使用**，包括但不限于销售、授权和商业服务
- ⚠️ 分发时须保留许可证文件和版权声明

> 如需商业许可，请联系作者获取单独授权。