内容
# 代理范围
**一个以目录为上下文的标准，加上一个只读的MCP服务器，为任何AI代理提供实时的结构化工作区感知能力，而无需重新读取所有内容，从而节省令牌。**
<div align="left">
<!-- Core Identity & Publishing -->
<a href="https://www.npmjs.com/package/agenticscope"><img src="https://img.shields.io/npm/v/agenticscope?style=for-the-badge&logo=npm" alt="NPM 版本" /></a>
<a href="https://www.npmjs.com/package/agenticscope"><img src="https://img.shields.io/npm/dt/agenticscope?style=for-the-badge&logo=npm" alt="NPM 下载量" /></a>
<a href="https://nodejs.org"><img src="https://img.shields.io/node/v/agenticscope?style=for-the-badge&logo=nodedotjs" alt="Node 版本" /></a>
<br/>
<!-- Build, Quality & Security -->
<a href="https://github.com/jessn-dev/agentic-scope/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/jessn-dev/agentic-scope/ci.yml?branch=main&style=for-the-badge&logo=github" alt="CI 状态" /></a>
<a href="https://snyk.io/test/npm/agenticscope"><img src="https://img.shields.io/snyk/vulnerabilities/npm/agenticscope?style=for-the-badge" alt="Snyk 漏洞" /></a>
<a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-Ready-blue?style=for-the-badge&logo=typescript" alt="TypeScript" /></a>
<a href="https://github.com/semantic-release/semantic-release"><img src="https://img.shields.io/badge/semantic--release-active-e10079?style=for-the-badge&logo=semantic-release" alt="Semantic Release" /></a>
<br/>
<!-- Development & Activity Stats -->
<a href="https://github.com/jessn-dev/agentic-scope/commits/main"><img src="https://img.shields.io/github/last-commit/jessn-dev/agentic-scope?style=for-the-badge" alt="最近提交" /></a>
<a href="https://github.com/jessn-dev/agentic-scope/issues"><img src="https://img.shields.io/github/issues/jessn-dev/agentic-scope?style=for-the-badge" alt="开放问题" /></a>
<a href="https://github.com/jessn-dev/agentic-scope/pulls"><img src="https://img.shields.io/github/issues-pr/jessn-dev/agentic-scope?style=for-the-badge" alt="拉取请求" /></a>
<a href="https://github.com/jessn-dev/agentic-scope"><img src="https://img.shields.io/github/repo-size/jessn-dev/agentic-scope?style=for-the-badge" alt="仓库大小" /></a>
<br/>
<!-- Visitors & License -->
<a href="https://visitorbadge.io/status?path=https%3A%2F%2Fgithub.com%2Fjessn-dev%2Fagentic-scope"><img src="https://api.visitorbadge.io/api/visitors?path=https%3A%2F%2Fgithub.com%2Fjessn-dev%2Fagentic-scope&countColor=%23263759&style=for-the-badge" alt="访问者数量" /></a>
<a href="./LICENSE"><img src="https://img.shields.io/npm/l/agenticscope?style=for-the-badge" alt="许可证" /></a>
<a href="http://makeapullrequest.com"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge" alt="欢迎PR" /></a>
</div>
> **许可证：** MIT · **要求：** Node.js ≥ 22 · 发布到npm时附带[出处](https://docs.npmjs.com/generating-provenance-statements)。
---
## 为什么我创建了这个
我遇到了同样的障碍。
我使用的每个AI编码工具——Claude Code、Cursor、Gemini、ChatGPT——都要求我提供上下文。所以我做了所有人都会做的事情：我编写了一个`AGENTS.md`、一个`CLAUDE.md`、一个`.cursorrules`。然后这些文件越来越大。很快，一个单独的“上下文文件”包含了我的编码标准、数据库架构、架构决策、当前任务笔记和一个角色提示——所有这些都堆积成一堆文本。
然后我看到了实际在后台发生的事情：**代理几乎在每次调用时都会重新读取整个文件。** 我必须为此付出代价——令牌、延迟和更快地达到我的计划限制。
这种挫折感促使我启动了这个项目。我希望我的AI工具能够更深入地了解我的工作，同时减少读取的内容。
## 我试图解决的痛点
我首先写下了这些，并将它们作为我的设计检查清单。一个庞大的上下文文件：
1. **浪费令牌。** 代理读取无关信息——模式而我正在修改CSS，部署笔记而我正在修复一个单元测试。大多数加载的内容都是噪音。
2. **混淆优先级。** 当行为规则（“永不使用`any`”）与静态参考数据（API规范）共享一个文件时，模型无法区分硬性规则和背景知识。
3. **产生工具噪音。** 每个供应商都想要自己的文件夹——`.claude/`、`.gemini/`、`.cursor/`——并且它们会逐渐失去同步。
4. **忽略工作区。** 我跨多个仓库工作。没有任何东西可以告诉代理“这里有每个项目，这里有未提交的更改，这里有正在进行的任务。” 每个会话都从头开始。
## 我如何构建它
我从简单开始，让每个痛点推动设计向前：
- 我将**庞大的文件**分成小文件——但代理仍然过度读取，因此仅靠组织无法解决问题。
- 我使其成为一个**索引，而不是约定。** 一个微小的`agenticscope.toml`清单是唯一始终加载的文件。它将**触发器**映射到**片段**，每个片段都有**类型**、**优先级**和**令牌成本**，在严格的**预算**下。
- 我使片段具有**类型**（`规则` / `知识` / `规范` / `角色`）和明确的优先级，以便行为规则不会被参考转储淹没。
- 我添加了一个 **`构建`步骤**，将单个`.scope/`源编译成每个供应商的原生文件——编辑一次，保持同步。
- 我编写了一个**只读MCP服务器**，以便代理可以询问整个工作区的结构化问题，而不是吞噬文件。
## 什么是agenticscope
两个部分共同工作。
### 1. `.scope/` 标准
一个可预测的布局，包含代理所需的一切，由一个微小的清单驱动：
```text
my-app/
├── agenticscope.toml # 清单 - 微小，唯一始终加载的文件
└── .scope/
├── rules/ # 类型：规则 - 行为，高优先级
├── knowledge/ # 类型：知识 - 静态参考，延迟加载
├── specs/ # 类型：规范 - 当前任务需求
├── personas/ # 类型：角色 - 可交换的代理“帽子”
└── memory/ # 持久项目知识（决策，偏好）
```
每个片段都通过两种方式与任务匹配，保持故意分离：
- **触发器** - glob模式，仅与具体文件路径匹配。
- **关键词** - 普通单词，与**任务文本**不区分大小写地匹配（子字符串）。
拆分它们可以避免假阳性（glob模式如`**/*.ts`永远不会泄漏到文本匹配中作为“ts”并获取无关单词）。普通单词触发器也被视为关键词，因此简单单词保持有效。
```toml
[scope]
version = "0.1.0"
name = "my-project"
budget = 4000 # 硬性上限（估计令牌）每个上下文包
precedence = "type" # 排序： “type”（规则优先）或“priority”
[[fragment]]
id = "coding-rules"
type = "rule"
path = ".scope/rules/coding.md"
triggers = ["**/*.ts", "**/*.tsx"] # 文件路径
keywords = ["refactor", "lint"] # 任务文本
priority = 100
[[fragment]]
id = "db-schema"
type = "knowledge"
path = ".scope/knowledge/schema.sql"
triggers = ["**/*.sql", "db/**"]
keywords = ["migration", "schema", "database"]
priority = 20
```
### 2. 只读MCP服务器
它为AI主机提供了一个实时、结构化的多项目工作区感知能力。它只读取 - 永远不会写入。
| 工具 | 它回答的问题 |
| :--- | :--- |
| `list_projects` | 工作区中存在哪些项目 |
| `list_subagents` | 项目定义哪些角色/子代理 |
| `list_plans` | 有哪些计划/规范正在进行 |
| `git_status` | 每个仓库的git状态（分支，ahead/behind，脏计数） |
| `grep_memory` | `.scope/memory/`文件的快速grep |
| `pack_context` | 任务 → 一个预算令牌的片段集 |
---
## 如何使用它
### 安装
```bash
# 运行无需安装：
npx agenticscope init
# 或全局安装CLI + MCP服务器：
npm i -g agenticscope
```
这给了你两个命令：`agenticscope`（CLI）和`agenticscope-mcp`（服务器）。
### 快速开始
```bash
agenticscope init # 在当前目录中搭建agenticscope.toml + .scope/
# 编辑清单 + 片段文件以匹配您的项目
agenticscope lint # 验证清单并检查每个片段路径
agenticscope build # 将.scope/编译成CLAUDE.md / GEMINI.md / AGENTS.md / .cursorrules
```
### 为任务打包上下文
`pack` 将任务解析为一个预算上下文块。只有匹配的片段被加载，直到预算用完：
```bash
$ agenticscope pack "fix the sql migration" -d ./my-app
► "fix the sql migration" — 匹配了 1 个片段（预算 4000，使用 86）
[knowledge] db-schema 86 tok
— 跳过了 coding-rules（无触发器匹配）
— 跳过了 qa-persona（无触发器匹配）
<!-- [knowledge] db-schema (86 tok) -->
CREATE TABLE users ( ... );
```
将打包的上下文直接输送到任何模型 - 包括原始的网络聊天：
```bash
agenticscope pack "fix auth bug" --raw | pbcopy # 然后粘贴到ChatGPT，Gemini等
```
传递具体的文件路径，以便glob触发器精确匹配：
```bash
agenticscope pack "refactor handler" -p src/api/handler.ts -p src/db/schema.sql
```
### CLI 参考
| 命令 | 执行操作 |
| :--- | :--- |
| `agenticscope init [dir]` | 搭建一个清单 + `.scope/` 树 |
| `agenticscope lint [dir]` | 验证清单；标记丢失的路径、重复的id、死亡片段和超过预算的片段 |
| `agenticscope build [dir]` | 将 `.scope/` 编译成供应商文件 (`-t, --target claude\|gemini\|agents\|cursor` 选择子集；`--check` 验证它们是否最新而无需写入 - 退出状态码非零，如果过时，理想情况下用于CI) |
| `agenticscope pack <task...>` | 将任务解析为预算上下文块 (`-d` 目录, `-p` 路径, `-b, --budget` 覆盖, `--exact` 分词器, `--raw`) |
| `agenticscope schema [dir]` | 为TOML编辑器自动补全生成 `schema/manifest.schema.json` (`-o` 输出路径) |
| `agenticscope mcp-config` | 打印可粘贴的MCP配置 (`--workspace`, `--host claude\|cursor\|generic`) |
**精确的令牌计数。** `pack` 默认使用快速的`chars/4`启发式估计算令牌。传递 `--exact` 使用捆绑的 `gpt-tokenizer`（cl100k）在预算紧张时进行精确计数。
### 连接MCP服务器
将任何支持MCP的主机指向服务器，并提供工作区根目录。然后主机实时调用工具。
**Claude Code / Claude Desktop** - 添加到您的MCP配置（`.mcp.json` 或 `claude_desktop_config.json`）：
```jsonc
{
"mcpServers": {
"agenticscope": {
"command": "npx",
"args": ["-y", "agenticscope-mcp", "--workspace", "~/Documents"]
}
}
}
```
相同的服务器适用于 **Gemini（Gemini CLI）**、**ChatGPT / OpenAI 代理**、**Cursor**、**Zed** 和 **Windsurf** - 每个都有自己的配置文件。您也可以使用 `AGENTICSCOPE_WORKSPACE` 环境变量设置工作区，而不是 `--workspace`，或者运行 `agenticscope mcp-config --host cursor` 打印一个可粘贴的块。
**默认_stdio；HTTP用于远程/托管使用。** 桌面主机通过stdio启动服务器。要作为共享服务运行，请通过Streamable HTTP启动：
```bash
agenticscope-mcp --http 3000 --workspace ~/Documents # 提供POST/GET http://localhost:3000/mcp
```
**安全构造。** 每个工具都是只读的，错误返回一个干净的 `isError` 结果而不是崩溃主机，并且 `project` 参数 **范围保护** 到工作区根目录 - 客户端无法诱使服务器读取 `/etc` 或 `../../secrets`。
连接后，我会问诸如 *"我的工作区中有什么正在进行？"* 之类的问题，主机调用 `list_plans` + `git_status` 并从结构化数据中回答 - **没有文件转储，没有令牌燃烧。** 就是这样。
---
## 您如何利用它
您不需要我确切的设置即可受益。有三种方法可以利用它。
**原样使用。** 在您的项目中搭建`.scope/`，并将MCP主机指向服务器。您将立即获得渐进的、预算的上下文和实时的 工作区感知。
**与任何供应商一起使用。**
- *MCP路径（实时工具）：* 任何支持MCP的主机 - Claude Code / Desktop，Gemini，ChatGPT / OpenAI代理，Cursor，Zed，Windsurf。
- *CLI路径（适用于所有地方，甚至原始网络聊天）：* `build` 从一个源生成每个供应商的文件；`pack` 打印一个预算块，您可以粘贴到任何模型中。
**用作您自己的基础。** 所有这些都是故意简单且MIT许可的。分叉它并：
- 定义您自己的片段类型超出规则/知识/规范/角色。
- 交换令牌估算器 - 它带有依赖项免费的`chars/4`启发式估算器；如果需要精确计数，请替换为真正的分词器。
- 添加您自己的MCP工具 - 服务器设计为只读，但模式可以干净地扩展。
- 替换解析器 - 触发器/优先级/预算模型是一个起点，而不是一个笼子。
## 需求
- **Node.js ≥ 22** （活跃的LTS；Node 18 和 20 已结束生命周期）。
- **您已经使用的AI工具** - Claude Code，Claude Desktop，Gemini，ChatGPT/OpenAI，Cursor等。
- **无需API密钥，无额外积分。** agenticscope完全本地运行，从不调用模型本身。通过Claude Code在Pro计划上驱动它不需要更多 - MCP工具在您的正常会话内运行。
## 项目布局
```text
agenticscope/
├── src/
│ ├── cli.ts # init / lint / build / pack
│ ├── core/ # 清单解析，片段解析，令牌预算，供应商构建
│ └── mcp/ # 只读MCP服务器 + 工具（工作区扫描，git，grep）
└── examples/
└── sample-workspace/ # 一个工作的.scope/项目，用于尝试命令
```
## 贡献
欢迎贡献。
- **发现了bug或有想法？** 打开一个问题： https://github.com/jessn-dev/agentic-scope/issues
- **发送拉取请求？** 分叉，分支，运行 `npm run typecheck && npm test` 然后推送，并描述更改。发行版和合并的更改记录在 [CHANGELOG.md](CHANGELOG.md) 中。
- **本地设置：**
```bash
npm install
npm run typecheck
npm test
npm run dev:cli -- lint examples/sample-workspace/api # 从源代码运行CLI
npm run dev:mcp # 从源代码运行MCP服务器
```
## 状态和路线图
`1.0` 行表示稳定的CLI + MCP工具表面和清单模式。标准和工具将继续演变；破坏性更改作为新的主要版本发布。反馈，分叉和竞争设计都欢迎 - 我想要更好的方法为代理提供上下文，而不是一个封闭的花园。
---
*我创建了这个，因为我厌倦了看着一个上下文文件我从未阅读却消耗了我无法承受的令牌。*
