项目概览与 .scope/ 标准

项目定位与设计动机

agenticscope 是一个"目录即上下文"标准，配合一个只读的 MCP（Model Context Protocol）服务器，让 AI 代理在多项目工作区中以结构化、按 token 预算的方式感知上下文，避免每次都全量重读文件 资料来源：README.md。

设计动机来自四个反复出现的痛点：单文件 context 浪费 token、规则与参考知识优先级混淆、.claude/、.gemini/、.cursor/ 等供应商目录彼此漂移、缺乏工作区级状态可见性 资料来源：README.md。

关键元数据

{
  "name": "agenticscope",
  "version": "0.2.1",
  "license": "MIT",
  "engines": { "node": ">=22" },
  "type": "module",
  "bin": {
    "agenticscope": "dist/cli.js",
    "agenticscope-mcp": "dist/mcp/server.js"
  }
}

最新版本 v0.2.1 修复了 repository.url 配置错误，并启用 OIDC trusted publishing，从 main 分支直接自动发布到 npm 资料来源：CHANGELOG.md、社区发布说明。

.scope/ 目录布局与 manifest

agenticscope 通过一个小巧的 TOML manifest驱动整个布局。manifest 是唯一始终被加载的文件，它将触发器映射到片段（fragment），每个片段都有类型、优先级和 token 成本，并受一个硬性预算约束 资料来源：README.md。

init 命令会同时生成 manifest 和 .scope/ 骨架目录 资料来源：src/cli.ts：

graph TD
  Root[项目根目录] --> Manifest[agenticscope.toml]
  Root --> Scope[".scope/"]
  Scope --> Rules[rules/<br/>type: rule]
  Scope --> Knowledge[knowledge/<br/>type: knowledge]
  Scope --> Specs[specs/<br/>type: spec]
  Scope --> Personas[personas/<br/>type: persona]
  Scope --> Memory[memory/<br/>持久化记忆]

每种片段类型有明确的语义角色：rule 承载高优先级行为规则，knowledge 存放静态参考，spec 描述当前任务需求，persona 表示可替换的代理"角色" 资料来源：context.md（types.ts zod schema 描述）、README.md。

片段匹配：触发器 vs 关键词

每个片段通过两种方式匹配任务，且二者严格分离以避免误命中 资料来源：README.md：

• triggers — glob 模式，仅与具体文件路径匹配。
• keywords — 普通单词，对任务文本做不区分大小写的子串匹配。

glob 模式（如 **/*.ts）绝不会泄漏到文本匹配中作为 "ts" 来抓取无关词（如 "artifacts"）；同时纯单词触发器也会被视为关键词以保留简单用法 资料来源：README.md、CHANGELOG.md（v0.2.0 修复 false-positive 问题）。

最小可运行 manifest 示例

[scope]
version    = "0.1.0"
name       = "my-project"
budget     = 4000
precedence = "type"

[[fragment]]
id       = "coding-rules"
type     = "rule"
path     = ".scope/rules/coding.md"
triggers = ["**/*.ts", "**/*.tsx"]
keywords = ["refactor", "lint"]
priority = 100

precedence 字段控制片段的最终排序：当设为 "type" 时按类型枚举顺序排列（rule 在前），设为 "priority" 时按数值 priority 排序 资料来源：CHANGELOG.md、context.md。

打包与供应商构建

pack 命令将任务解析为一个符合预算的上下文块：仅加载匹配的片段，并在预算耗尽时停止；同时记录"跳过原因"以便调试 资料来源：README.md：

$ agenticscope pack "fix the sql migration" -d ./my-app
► "fix the sql migration" — matched 1 fragment(s) (budget 4000, used 86)
  [knowledge] db-schema             86 tok
  — skipped coding-rules (no trigger match)

build 命令把同一份 .scope/ 源码编译为所有供应商原生的上下文文件：CLAUDE.md、GEMINI.md、AGENTS.md、.cursorrules 资料来源：src/core/vendor.ts。输出文件顶部会插入 <!-- GENERATED by agenticscope --> 提示，避免手工编辑后被覆盖 资料来源：src/core/vendor.ts。

token 估算

token 计数使用无依赖的 chars/4 启发式实现，可在 src/core/tokens.ts 单独替换为精确 tokenizer（如 tiktoken） 资料来源：src/core/tokens.ts、README.md。

依赖与质量保障

项目以 TypeScript（ESM / NodeNext）开发，运行测试使用 Vitest，测试套件覆盖 manifest 解析、触发器匹配、pack 预算、vendor 构建、memory grep 等 18 个用例 资料来源：vitest.config.ts、context.md。prepublishOnly 钩子保证发布前一定先 tsc 编译，CI 通过 GitHub Actions 同时运行 typecheck + test + build 资料来源：package.json、context.md。运行时核心依赖为 @modelcontextprotocol/sdk、commander、picomatch、simple-git、smol-toml、zod 资料来源：package.json。

参见

• CLI 命令参考
• MCP 服务器与工具集
• 片段解析与预算算法
• 供应商构建细节

1. 总体定位与设计目标

agenticscope 的核心引擎解决的是 AI 编码代理在多项目中反复吞下整个上下文文件的问题。README.md 将其定位为「一个以目录为载体的上下文标准 + 一个只读 MCP 服务器」，让代理对工作区拥有「活的、结构化的、按令牌预算感知的」视图，而非一次性灌入 README.md:1-40。

整套设计围绕四个明确痛点展开：浪费令牌、规则与参考材料混优先级、各家工具目录（.claude/、.gemini/、.cursor/）漂移、缺少工作区级感知 README.md:42-60。核心引擎因此被划分为两条主线：编译时的 .scope/ 标准与清单，以及运行时的 MCP 工具面。CLI 与 MCP 服务器共用同一套 src/core/ 实现，确保任何工作流拿到的解析、打包、令牌估算结果完全一致。

2. `.scope/` 标准与清单结构

项目以一个轻量 TOML 清单 agenticscope.toml 作为唯一始终加载的文件，配合标准化的 .scope/ 子目录树（rules/、knowledge/、specs/、personas/、memory/）README.md:30-50。清单由 zod schema 强校验，定义在 src/core/types.ts 中：

• scope 块声明版本、名称、budget（硬性令牌上限）以及 precedence（"type" 或 "priority"）src/core/types.ts:35-60。
• [[fragment]] 条目包含 id、type（rule/knowledge/spec/persona）、path、triggers（glob 路径）、keywords（文本词）、priority、always src/core/types.ts:18-34。

类型本身携带语义优先级：rule > spec > persona > knowledge，常量 TYPE_PRECEDENCE 在排序时被直接查表使用 src/core/types.ts:8-16。这种「类型即优先级」的设计是核心引擎让行为准则不被参考资料淹没的根本机制。

3. 匹配、打包与令牌预算

核心引擎的运行时关键路径由 src/core/fragments.ts 提供（详见 context.md 中描述），其关键设计点有二：

1. triggers 与 keywords 完全分离：前者只对具体文件路径做 glob 匹配，后者只对任务文本做子串（不区分大小写）匹配。这避免了 **/*.ts 这类 glob 把 "ts" 当作关键词误匹配 "artifacts" 等词——该问题在 v0.2.0 中被显式修复 CHANGELOG.md:12-15。
2. 硬性预算截断：pack 按 precedence 排序后按类型/优先级累加片段，直至超出 budget 即停止，并记录「skipped」原因 context.md:24-30。令牌估算由 src/core/tokens.ts 的 estimateTokens 提供，采用无依赖的 chars/4 启发式；若需要精确值，可单点替换该函数 src/core/tokens.ts:7-15。

下列流程图描述了从用户任务到打包上下文的完整数据流：

flowchart LR
    A[任务文本 + 文件路径] --> B[matchTriggers<br/>glob vs 关键词分离]
    B --> C[按 precedence 排序<br/>type 或 priority]
    C --> D[按 budget 累加<br/>chars/4 估算]
    D --> E[renderPack<br/>带跳过原因]
    E --> F[最终上下文块]

4. 供应商编译与 CLI 入口

build 步骤把单一份 .scope/ 源编译为多家代理原生的配置文件（CLAUDE.md、GEMINI.md、AGENTS.md、.cursorrules），由 src/core/vendor.ts 的 compile 与 build 实现。compile 按固定顺序（rule → spec → persona → knowledge）拼接片段，缺失文件以 [missing: <path>] 占位而非中断 src/core/vendor.ts:1-30。build 写入所有默认目标并返回 BuildResult.written 列表 src/core/vendor.ts:32-43。

CLI 入口在 src/cli.ts 暴露四个命令：init 脚手架清单与 .scope/ 树，lint 校验路径与重复 id，build 编译供应商文件，pack 解析任务为预算化上下文块 README.md:78-92。init 命令同时生成示例 rule、knowledge、persona、memory 文件，便于新用户快速验证 src/cli.ts:1-60。

5. 运行时：只读 MCP 服务器

核心引擎的另一半是只读 MCP 服务器，承载在 bin 入口 agenticscope-mcp 下（package.json 中声明）。它通过 stdio 传输协议向 AI 主机暴露六个工具：list_projects、list_subagents、list_plans、git_status、grep_memory、pack_context，每个工具调用都被 guard() 包裹，发生错误时返回干净的 isError 结果而非让进程崩溃 context.md:33-40。这种只读设计意味着代理只能询问工作区而不能擅自修改它——这也是当前架构的一个明确护栏（CHANGELOG.md 中已修复早期会让服务器崩溃的工具错误）。

6. 已知限制与扩展点

context.md 列出了几条与核心引擎直接相关的演进方向：缺少 --budget CLI 覆盖、schema/manifest.schema.json 仍为空（用于 TOML 自动补全）、MCP 目前仅支持 stdio 而无 HTTP 传输、list_subagents/list_plans 仍要求绝对路径而非项目名解析 context.md:55-70。此外，开发者被显式鼓励替换令牌估算器、扩展片段类型或新增 MCP 工具——核心引擎是「起点而非牢笼」README.md:118-130。

只读 MCP 服务器与工具

概述与设计定位

agenticscope 提供了一个基于 Model Context Protocol（MCP） 的只读服务器，作为整套项目的“实时感知”层。它将本地多项目工作空间的目录结构、Git 状态、记忆文件与预算化上下文片段，以结构化 JSON 的形式暴露给任何 MCP 兼容的 AI 主机（Claude Code/Desktop、Gemini CLI、Cursor、Zed、Windsurf 等），但 从不向磁盘写入任何内容——这是有意为之的设计原则 资料来源：README.md。

服务器随包发布后可通过 agenticscope-mcp 命令启动，并采用 stdio 传输——因为 stdout 保留给 MCP 协议流，日志只能输出到 stderr 资料来源：src/mcp/server.ts。

服务器引导与工作空间解析

入口脚本通过 resolveWorkspace() 按以下优先级解析工作空间根目录 资料来源：src/mcp/server.ts：

1. 命令行 --workspace 参数；
2. 环境变量 AGENTICSCOPE_WORKSPACE；
3. 当前进程工作目录（process.cwd()）。

~ 会被展开为用户主目录。该根目录随后被所有工具共享，作为扫描项目、读取 .scope/、查询 Git 与 grep 记忆文件的边界。

六大工具清单

服务器注册了六个只读工具，每个工具回答一个具体的“工作空间问题”：

每个工具的参数都通过 Zod schema 定义，AI 主机调用时即获得自动校验与类型提示。

数据流架构

下图描述了一次典型的 pack_context 调用如何在 agenticscope 内部流转：

flowchart LR
  Host["AI 主机<br/>(Claude Code/Gemini/Cursor)"]
  Server["MCP Server<br/>(src/mcp/server.ts)"]
  Ws["scanProjects()<br/>(src/mcp/workspace.ts)"]
  Manifest["loadManifest()<br/>(src/core/manifest.ts)"]
  Pack["pack() + renderPack()<br/>(src/core/fragments.ts)"]
  Tok["estimateTokens()<br/>(src/core/tokens.ts)"]
  FS[".scope/ 目录与 TOML 清单"]

  Host -- "MCP 请求 (stdio)" --> Server
  Server -- "解析工作空间根" --> Ws
  Server -- "解析 agenticscope.toml" --> Manifest
  Manifest -- "读取 .scope/**" --> FS
  Server -- "task + paths + budget" --> Pack
  Pack -- "调用 tokens 估算" --> Tok
  Pack -- "结构化 JSON 结果" --> Host

Git 状态工具实现细节

git_status 是六个工具中唯一异步调用外部依赖（simple-git）的。它检查目标目录是否存在 .git/，若不存在则返回 { isRepo: false }；若存在则读取 status()，汇总 branch / ahead / behind / dirtyFiles / staged / tracking 字段。任意抛出都被捕获并以 error 字段返回，而不是向上冒泡 资料来源：src/mcp/git.ts。

该工具的设计保持严格只读：从不 add、commit、push 或重置任何东西，从而与整套 MCP 服务器的 “never writes” 原则一致 资料来源：README.md。

错误处理：`guard()` 包装器

每个工具的处理器都被 guard() 包装，其作用是把抛出的异常转换为符合 MCP 规范的 { isError: true, content: [...] } 结果，而不是让进程崩溃 资料来源：src/mcp/server.ts。

这是 v0.2.0 引入的一项修复，CHANGELOG 明确指出：“MCP tool errors now return a clean isError result instead of crashing the server.” 资料来源：CHANGELOG.md。fail() 辅助函数还会把 Error.message 序列化为可读的文本内容，避免暴露堆栈。

安装与宿主配置

服务器通过 npm 包的 bin 字段同时发布 资料来源：package.json：

{
  "mcpServers": {
    "agenticscope": {
      "command": "npx",
      "args": ["-y", "agenticscope-mcp", "--workspace", "~/Documents"]
    }
  }
}

npx -y agenticscope-mcp 会拉取最新版本并启动服务器；也可以全局安装 npm i -g agenticscope 后直接调用 资料来源：README.md。

与其他模块的关系

MCP 服务器复用了 src/core/ 中的所有领域逻辑：

• loadManifest() 解析 agenticscope.toml 资料来源：src/core/manifest.ts；
• pack() / renderPack() 计算触发器匹配、应用类型或优先级排序，并在硬性 budget 下裁剪片段 资料来源：src/core/fragments.ts；
• estimateTokens() 使用 chars/4 启发式，无需安装任何原生 tokenizer 资料来源：src/core/tokens.ts。

这种复用意味着 CLI 的 pack 命令和 MCP 的 pack_context 工具产出完全一致——只是前者打印到终端，后者返回 JSON。

已知限制与路线图

context.md 中记录了若干待改进点 资料来源：context.md：

• list_subagents 与 list_plans 当前要求传入 绝对路径作为 project 参数，未来计划允许使用项目名解析。
• 服务器目前仅支持 stdio 传输；HTTP 传输（用于远程/托管场景）列入 Tier 4 路线图（#12）。
• 缺少 路径作用域守卫：MCP 工具的 project 参数理论上可指向工作空间之外的目录，后续将加入限制（#13）。
• --budget 命令行覆写与 lint 对超大片段的告警计划在 Tier 3（#6）落地。

小结

只读 MCP 服务器是 agenticscope “让 AI 少读多知” 理念的入口：AI 主机不再需要把整个工作空间吞进上下文，而是按需向这六个工具发起结构化查询。设计上通过 guard() 容错、simpleGit 只读封装、~/$ENV/cwd 多源工作空间解析与 chars/4 启发式 token 估算，实现了零密钥、零外部调用、零本地写入的轻量集成。配合 CLI 的 init / lint / build / pack，它构成了从“原始仓库”到“被代理实时感知的工作空间”的完整闭环。

See Also

• .scope/ Standard & Manifest Schema — 片段类型、优先级与预算模型
• CLI Reference: init / lint / build / pack — 命令详解
• Token Budgeting & Estimator — chars/4 启发式与可选真实 tokenizer

CLI 使用、Vendor 构建与发布

本页面向使用者与维护者,系统说明 agenticscope 的命令行工具、build 生成的 vendor 文件,以及从源码到 npm 发布的完整流程。agenticscope 由两个独立的 npm 二进制组成:agenticscope(CLI) 与 agenticscope-mcp(只读 MCP 服务器),后者在另一篇页面详述。CLI 的职责是初始化、校验、把 .scope/ 编译成各 AI 厂商的原生文件,以及在需要时打包上下文片段。

资料来源：README.md:1-30, package.json:1-60

Pitfall Log / 踩坑日志

项目：jessn-dev/agentic-scope-mcp-retrieval

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 agentic-scope-mcp-retrieval 与安装入口 agenticscope 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 复现命令：npx agenticscope
• 证据：identity.distribution | https://github.com/jessn-dev/agentic-scope | repo=agentic-scope-mcp-retrieval; install=agenticscope

2. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/jessn-dev/agentic-scope | host_targets=mcp_host, claude_code, claude, cursor, chatgpt

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/jessn-dev/agentic-scope | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/jessn-dev/agentic-scope | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/jessn-dev/agentic-scope | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/jessn-dev/agentic-scope | no_demo; severity=medium

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/jessn-dev/agentic-scope | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/jessn-dev/agentic-scope | release_recency=unknown