# https://github.com/jessn-dev/agentic-scope 项目说明书 生成时间：2026-06-24 14:56:44 UTC ## 目录 - [Project Overview & the .scope/ Standard](#page-overview) - [System Architecture & Core Engine](#page-architecture) - [Read-only MCP Server & Tools](#page-mcp) - [CLI Usage, Vendor Build & Deployment](#page-usage) ## Project Overview & the .scope/ Standard ### 相关页面 相关主题：[System Architecture & Core Engine](#page-architecture), [CLI Usage, Vendor Build & Deployment](#page-usage)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/jessn-dev/agentic-scope/blob/main/README.md) - [package.json](https://github.com/jessn-dev/agentic-scope/blob/main/package.json) - [CHANGELOG.md](https://github.com/jessn-dev/agentic-scope/blob/main/CHANGELOG.md) - [src/cli.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/cli.ts) - [src/core/vendor.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/core/vendor.ts) - [src/core/tokens.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/core/tokens.ts) - [context.md](https://github.com/jessn-dev/agentic-scope/blob/main/context.md) - [vitest.config.ts](https://github.com/jessn-dev/agentic-scope/blob/main/vitest.config.ts)
# 项目概览与 .scope/ 标准 ## 项目定位与设计动机 agenticscope 是一个"目录即上下文"标准，配合一个**只读**的 MCP（Model Context Protocol）服务器，让 AI 代理在多项目工作区中以结构化、按 token 预算的方式感知上下文，避免每次都全量重读文件 资料来源：[README.md](https://github.com/jessn-dev/agentic-scope/blob/main/README.md)。 设计动机来自四个反复出现的痛点：单文件 context 浪费 token、规则与参考知识优先级混淆、`.claude/`、`.gemini/`、`.cursor/` 等供应商目录彼此漂移、缺乏工作区级状态可见性 资料来源：[README.md](https://github.com/jessn-dev/agentic-scope/blob/main/README.md)。 ### 关键元数据 ```jsonc { "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](https://github.com/jessn-dev/agentic-scope/blob/main/CHANGELOG.md)、社区发布说明。 ## .scope/ 目录布局与 manifest `agenticscope` 通过一个**小巧的 TOML manifest**驱动整个布局。manifest 是唯一始终被加载的文件，它将触发器映射到片段（fragment），每个片段都有类型、优先级和 token 成本，并受一个硬性预算约束 资料来源：[README.md](https://github.com/jessn-dev/agentic-scope/blob/main/README.md)。 `init` 命令会同时生成 manifest 和 `.scope/` 骨架目录 资料来源：[src/cli.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/cli.ts)： ```mermaid graph TD Root[项目根目录] --> Manifest[agenticscope.toml] Root --> Scope[".scope/"] Scope --> Rules[rules/
type: rule] Scope --> Knowledge[knowledge/
type: knowledge] Scope --> Specs[specs/
type: spec] Scope --> Personas[personas/
type: persona] Scope --> Memory[memory/
持久化记忆] ``` 每种片段类型有明确的语义角色：`rule` 承载高优先级行为规则，`knowledge` 存放静态参考，`spec` 描述当前任务需求，`persona` 表示可替换的代理"角色" 资料来源：[context.md](https://github.com/jessn-dev/agentic-scope/blob/main/context.md)（`types.ts` zod schema 描述）、[README.md](https://github.com/jessn-dev/agentic-scope/blob/main/README.md)。 ## 片段匹配：触发器 vs 关键词 每个片段通过两种方式匹配任务，且二者**严格分离**以避免误命中 资料来源：[README.md](https://github.com/jessn-dev/agentic-scope/blob/main/README.md)： - **`triggers`** — glob 模式，仅与具体文件路径匹配。 - **`keywords`** — 普通单词，对任务文本做不区分大小写的子串匹配。 glob 模式（如 `**/*.ts`）绝不会泄漏到文本匹配中作为 "ts" 来抓取无关词（如 "artifacts"）；同时纯单词触发器也会被视为关键词以保留简单用法 资料来源：[README.md](https://github.com/jessn-dev/agentic-scope/blob/main/README.md)、[CHANGELOG.md](https://github.com/jessn-dev/agentic-scope/blob/main/CHANGELOG.md)（v0.2.0 修复 false-positive 问题）。 ### 最小可运行 manifest 示例 ```toml [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](https://github.com/jessn-dev/agentic-scope/blob/main/CHANGELOG.md)、[context.md](https://github.com/jessn-dev/agentic-scope/blob/main/context.md)。 ## 打包与供应商构建 `pack` 命令将任务解析为一个**符合预算的上下文块**：仅加载匹配的片段，并在预算耗尽时停止；同时记录"跳过原因"以便调试 资料来源：[README.md](https://github.com/jessn-dev/agentic-scope/blob/main/README.md)： ```bash $ 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](https://github.com/jessn-dev/agentic-scope/blob/main/src/core/vendor.ts)。输出文件顶部会插入 `` 提示，避免手工编辑后被覆盖 资料来源：[src/core/vendor.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/core/vendor.ts)。 ### token 估算 token 计数使用无依赖的 `chars/4` 启发式实现，可在 `src/core/tokens.ts` 单独替换为精确 tokenizer（如 tiktoken） 资料来源：[src/core/tokens.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/core/tokens.ts)、[README.md](https://github.com/jessn-dev/agentic-scope/blob/main/README.md)。 ## 依赖与质量保障 项目以 TypeScript（ESM / NodeNext）开发，运行测试使用 Vitest，测试套件覆盖 manifest 解析、触发器匹配、pack 预算、vendor 构建、memory grep 等 18 个用例 资料来源：[vitest.config.ts](https://github.com/jessn-dev/agentic-scope/blob/main/vitest.config.ts)、[context.md](https://github.com/jessn-dev/agentic-scope/blob/main/context.md)。`prepublishOnly` 钩子保证发布前一定先 `tsc` 编译，CI 通过 GitHub Actions 同时运行 `typecheck + test + build` 资料来源：[package.json](https://github.com/jessn-dev/agentic-scope/blob/main/package.json)、[context.md](https://github.com/jessn-dev/agentic-scope/blob/main/context.md)。运行时核心依赖为 `@modelcontextprotocol/sdk`、`commander`、`picomatch`、`simple-git`、`smol-toml`、`zod` 资料来源：[package.json](https://github.com/jessn-dev/agentic-scope/blob/main/package.json)。 ## 参见 - [CLI 命令参考](#) - [MCP 服务器与工具集](#) - [片段解析与预算算法](#) - [供应商构建细节](#) --- ## System Architecture & Core Engine ### 相关页面 相关主题：[Project Overview & the .scope/ Standard](#page-overview), [Read-only MCP Server & Tools](#page-mcp), [CLI Usage, Vendor Build & Deployment](#page-usage)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/jessn-dev/agentic-scope/blob/main/README.md) - [package.json](https://github.com/jessn-dev/agentic-scope/blob/main/package.json) - [CHANGELOG.md](https://github.com/jessn-dev/agentic-scope/blob/main/CHANGELOG.md) - [context.md](https://github.com/jessn-dev/agentic-scope/blob/main/context.md) - [src/core/types.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/core/types.ts) - [src/core/tokens.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/core/tokens.ts) - [src/core/vendor.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/core/vendor.ts) - [src/cli.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/cli.ts)
# System Architecture & Core Engine ## 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]()。 下列流程图描述了从用户任务到打包上下文的完整数据流： ```mermaid flowchart LR A[任务文本 + 文件路径] --> B[matchTriggers
glob vs 关键词分离] B --> C[按 precedence 排序
type 或 priority] C --> D[按 budget 累加
chars/4 估算] D --> E[renderPack
带跳过原因] 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: ]` 占位而非中断 [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]()。 --- ## See Also - 主页与快速上手：[README.md](https://github.com/jessn-dev/agentic-scope/blob/main/README.md) - 变更历史：[CHANGELOG.md](https://github.com/jessn-dev/agentic-scope/blob/main/CHANGELOG.md) - 项目内部状态与待办：[context.md](https://github.com/jessn-dev/agentic-scope/blob/main/context.md) - v0.2.1 修复（仓库 URL 与 OIDC 自动发布）：[Release notes](https://github.com/jessn-dev/agentic-scope/compare/v0.2.0...v0.2.1) --- ## Read-only MCP Server & Tools ### 相关页面 相关主题：[System Architecture & Core Engine](#page-architecture), [CLI Usage, Vendor Build & Deployment](#page-usage)
相关源码文件 以下源码文件用于生成本页说明： - [src/mcp/server.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/mcp/server.ts) - [src/mcp/git.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/mcp/git.ts) - [src/mcp/workspace.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/mcp/workspace.ts) - [src/mcp/grep.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/mcp/grep.ts) - [src/core/manifest.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/core/manifest.ts) - [src/core/fragments.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/core/fragments.ts) - [src/core/tokens.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/core/tokens.ts) - [package.json](https://github.com/jessn-dev/agentic-scope/blob/main/package.json) - [README.md](https://github.com/jessn-dev/agentic-scope/blob/main/README.md) - [context.md](https://github.com/jessn-dev/agentic-scope/blob/main/context.md)
# 只读 MCP 服务器与工具 ## 概述与设计定位 agenticscope 提供了一个基于 [Model Context Protocol（MCP）](https://modelcontextprotocol.io) 的只读服务器，作为整套项目的“实时感知”层。它将本地多项目工作空间的目录结构、Git 状态、记忆文件与预算化上下文片段，以结构化 JSON 的形式暴露给任何 MCP 兼容的 AI 主机（Claude Code/Desktop、Gemini CLI、Cursor、Zed、Windsurf 等），但 **从不向磁盘写入任何内容**——这是有意为之的设计原则 资料来源：[README.md](https://github.com/jessn-dev/agentic-scope/blob/main/README.md)。 服务器随包发布后可通过 `agenticscope-mcp` 命令启动，并采用 **stdio 传输**——因为 stdout 保留给 MCP 协议流，日志只能输出到 stderr 资料来源：[src/mcp/server.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/mcp/server.ts#L46-L48)。 ## 服务器引导与工作空间解析 入口脚本通过 `resolveWorkspace()` 按以下优先级解析工作空间根目录 资料来源：[src/mcp/server.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/mcp/server.ts#L8-L13)： 1. 命令行 `--workspace` 参数； 2. 环境变量 `AGENTICSCOPE_WORKSPACE`； 3. 当前进程工作目录（`process.cwd()`）。 `~` 会被展开为用户主目录。该根目录随后被所有工具共享，作为扫描项目、读取 `.scope/`、查询 Git 与 grep 记忆文件的边界。 ## 六大工具清单 服务器注册了六个只读工具，每个工具回答一个具体的“工作空间问题”： | 工具名称 | 回答的问题 | 主要来源 | | :--- | :--- | :--- | | `list_projects` | 工作空间内存在哪些项目 | [workspace.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/mcp/workspace.ts) | | `list_subagents` | 项目声明了哪些 persona / 子代理 | [workspace.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/mcp/workspace.ts) | | `list_plans` | 当前有哪些计划/规格在执行中 | [workspace.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/mcp/workspace.ts) | | `git_status` | 每个仓库的分支、领先/落后与脏文件数 | [src/mcp/git.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/mcp/git.ts) | | `grep_memory` | 在 `.scope/memory/` 下做快速文本检索 | [src/mcp/grep.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/mcp/grep.ts) | | `pack_context` | 把一个任务映射为预算化上下文片段集 | [src/core/fragments.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/core/fragments.ts) | 每个工具的参数都通过 [Zod](https://zod.dev) schema 定义，AI 主机调用时即获得自动校验与类型提示。 ## 数据流架构 下图描述了一次典型的 `pack_context` 调用如何在 agenticscope 内部流转： ```mermaid flowchart LR Host["AI 主机
(Claude Code/Gemini/Cursor)"] Server["MCP Server
(src/mcp/server.ts)"] Ws["scanProjects()
(src/mcp/workspace.ts)"] Manifest["loadManifest()
(src/core/manifest.ts)"] Pack["pack() + renderPack()
(src/core/fragments.ts)"] Tok["estimateTokens()
(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](https://github.com/jessn-dev/agentic-scope/blob/main/src/mcp/git.ts#L7-L26)。 该工具的设计保持严格只读：从不 `add`、`commit`、`push` 或重置任何东西，从而与整套 MCP 服务器的 “never writes” 原则一致 资料来源：[README.md](https://github.com/jessn-dev/agentic-scope/blob/main/README.md)。 ## 错误处理：`guard()` 包装器 每个工具的处理器都被 `guard()` 包装，其作用是把抛出的异常转换为符合 MCP 规范的 `{ isError: true, content: [...] }` 结果，而不是让进程崩溃 资料来源：[src/mcp/server.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/mcp/server.ts#L21-L29)。 这是 v0.2.0 引入的一项修复，CHANGELOG 明确指出：“MCP tool errors now return a clean `isError` result instead of crashing the server.” 资料来源：[CHANGELOG.md](https://github.com/jessn-dev/agentic-scope/blob/main/CHANGELOG.md)。`fail()` 辅助函数还会把 `Error.message` 序列化为可读的文本内容，避免暴露堆栈。 ## 安装与宿主配置 服务器通过 npm 包的 `bin` 字段同时发布 资料来源：[package.json](https://github.com/jessn-dev/agentic-scope/blob/main/package.json#L18-L21)： ```jsonc { "mcpServers": { "agenticscope": { "command": "npx", "args": ["-y", "agenticscope-mcp", "--workspace", "~/Documents"] } } } ``` `npx -y agenticscope-mcp` 会拉取最新版本并启动服务器；也可以全局安装 `npm i -g agenticscope` 后直接调用 资料来源：[README.md](https://github.com/jessn-dev/agentic-scope/blob/main/README.md)。 ## 与其他模块的关系 MCP 服务器复用了 `src/core/` 中的所有领域逻辑： - `loadManifest()` 解析 `agenticscope.toml` 资料来源：[src/core/manifest.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/core/manifest.ts)； - `pack()` / `renderPack()` 计算触发器匹配、应用类型或优先级排序，并在硬性 `budget` 下裁剪片段 资料来源：[src/core/fragments.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/core/fragments.ts)； - `estimateTokens()` 使用 `chars/4` 启发式，无需安装任何原生 tokenizer 资料来源：[src/core/tokens.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/core/tokens.ts)。 这种复用意味着 CLI 的 `pack` 命令和 MCP 的 `pack_context` 工具产出完全一致——只是前者打印到终端，后者返回 JSON。 ## 已知限制与路线图 context.md 中记录了若干待改进点 资料来源：[context.md](https://github.com/jessn-dev/agentic-scope/blob/main/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 Usage, Vendor Build & Deployment ### 相关页面 相关主题：[Project Overview & the .scope/ Standard](#page-overview), [System Architecture & Core Engine](#page-architecture), [Read-only MCP Server & Tools](#page-mcp)
相关源码文件 以下源码文件用于生成本页说明： - [package.json](https://github.com/jessn-dev/agentic-scope/blob/main/package.json) - [README.md](https://github.com/jessn-dev/agentic-scope/blob/main/README.md) - [CHANGELOG.md](https://github.com/jessn-dev/agentic-scope/blob/main/CHANGELOG.md) - [context.md](https://github.com/jessn-dev/agentic-scope/blob/main/context.md) - [src/core/vendor.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/core/vendor.ts) - [src/core/types.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/core/types.ts) - [src/core/tokens.ts](https://github.com/jessn-dev/agentic-scope/blob/main/src/core/tokens.ts) - [vitest.config.ts](https://github.com/jessn-dev/agentic-scope/blob/main/vitest.config.ts)
# CLI 使用、Vendor 构建与发布 本页面向使用者与维护者,系统说明 `agenticscope` 的命令行工具、`build` 生成的 vendor 文件,以及从源码到 npm 发布的完整流程。`agenticscope` 由两个独立的 npm 二进制组成:**`agenticscope`(CLI)** 与 **`agenticscope-mcp`(只读 MCP 服务器)**,后者在另一篇页面详述。CLI 的职责是初始化、校验、把 `.scope/` 编译成各 AI 厂商的原生文件,以及在需要时打包上下文片段。 资料来源：[README.md:1-30](), [package.json:1-60]() --- ## CLI 命令总览 `agenticscope` CLI 共暴露四个核心命令,外加独立的 MCP 服务器命令。所有命令均通过 `commander` 调度,并支持 `tsx`(开发态)或编译后的 `dist/cli.js`(生产态)运行。资料来源：[package.json:24-34](), [README.md:96-114]() | 命令 | 作用 | 典型用途 | | :--- | :--- | :--- | | `agenticscope init [dir]` | 在指定目录生成 `agenticscope.toml` 与 `.scope/` 目录骨架 | 新项目起步 | | `agenticscope lint [dir]` | 校验 manifest、检测重复 id、死链接、不存在的 fragment 路径 | CI 中的快速质量门禁 | | `agenticscope build [dir]` | 把 `.scope/` 编译为 `CLAUDE.md` / `GEMINI.md` / `AGENTS.md` / `.cursorrules` | 提交前同步各厂商上下文 | | `agenticscope pack ` | 根据任务文本与路径解析片段,在 token 预算内输出上下文块 | 给 Agent 喂料 | | `agenticscope-mcp --workspace ` | 启动只读 MCP 服务器,暴露 6 个工具 | 接入 Claude Code / Cursor 等 MCP 主机 | `pack` 命令支持三个常用参数:`-d/--dir` 指定项目根、`-p/--path` 列出涉及到的具体文件路径、`--raw` 输出不含渲染头部的纯文本。资料来源：[README.md:104-114]() --- ## Vendor Build 工作机制 `build` 是整个工具链的"单源真相"枢纽:维护者只编辑 `.scope/` 下的文件与 `agenticscope.toml`,由 `build` 一次产出多个厂商的原生上下文文件,避免多份规则副本漂移。资料来源：[README.md:18-30](), [CHANGELOG.md:18-26]() `src/core/vendor.ts` 中的 `compile(loaded)` 按 `ORDER` 数组定义的类型顺序遍历 `manifest.fragment`,依次为 `rule → spec → persona → knowledge`(对应 `TYPE_PRECEDENCE` 中的 3 / 2 / 1 / 0)。每种类型生成一个二级标题,在其下逐个 `### ` 嵌入对应 fragment 文件的全文。如果 fragment 文件缺失,则写入 `> [missing: ]` 占位提示。资料来源：[src/core/vendor.ts:1-30](), [src/core/types.ts:14-19]() `build(loaded, targets)` 在 `compile` 之上,按 `VENDOR_TARGETS` 列表将同一份 Markdown 文档分别写入项目根目录下的 `CLAUDE.md`、`GEMINI.md`、`AGENTS.md`、`.cursorrules`,返回写入的文件名数组。这意味着构建输出**对所有厂商使用同一份正文**,不区分 vendor 风格——CHANGELOG 与 `context.md` 均把这一行为列为已知限制,后续可能通过 `--target` 标志或 per-vendor 格式化扩展(议题 #8)。资料来源：[src/core/vendor.ts:30-45](), [context.md:10-13]() > **关键约束**:`vendor.ts` 用纯 `fs` 同步写入;它会**静默覆盖**现有的 vendor 文件。每次 `build` 前请确认没有未提交的手动修改,否则会被生成的 GENERATED 标记覆盖。资料来源：[src/core/vendor.ts:18-25]() --- ## 构建、测试与发布流水线 下图为从源码到 npm 的完整流水线,涵盖本地开发、CI 校验与自动发版三个阶段: ```mermaid flowchart LR A[编辑 .scope/
+ agenticscope.toml] --> B[agenticscope lint] B --> C[agenticscope build] C --> D[CLAUDE.md
GEMINI.md
AGENTS.md
.cursorrules] A --> E[npm run build
tsc -p tsconfig.json] E --> F[dist/cli.js
dist/mcp/server.js] F --> G{语义化发布} G -- Conventional Commits --> H[semantic-release] H -- tag v* --> I[npm publish --provenance] H --> J[CHANGELOG.md 自动生成] B -.失败.-> K((CI 红灯)) E -.失败.-> K ``` `npm scripts` 在 `package.json` 中明确划分了开发与生产两套路径:`dev:cli` / `dev:mcp` 用 `tsx` 直接运行 TypeScript 源码,便于热迭代;`build` 调用 `tsc -p tsconfig.json` 生成 `dist/`;`prepublishOnly` 钩子确保发布前一定先完成编译;`typecheck` 只做类型检查、不输出文件,适合在 CI 中快速失败。资料来源：[package.json:24-34]() 测试方面,`vitest.config.ts` 把测试范围限定在 `tests/**/*.test.ts`,共 18 个用例覆盖 manifest 解析、trigger 匹配、pack/budget 计算、vendor 编译与 grep 工具。`npm test` 是 CI 的强制门禁。资料来源：[vitest.config.ts:1-6](), [context.md:18-21]() 发版由 `semantic-release` 驱动:`0.2.0` 之前的版本手工维护,自 `0.2.1` 起改为根据 push 到 `main` 的 Conventional Commits 自动生成版本号与 CHANGELOG。`v0.2.1` 修复了 `repository.url` 错误并启用 OIDC trusted publishing,从而取代传统的 `NPM_TOKEN` 手动发布。CI 工作流位于 `.github/workflows/publish.yml`,通过 tag `v*` 触发 `npm publish --provenance`,同时启用 provenance 证书以提升供应链透明度。资料来源：[CHANGELOG.md:1-8](), [context.md:24-29](), [README.md:152-166]() --- ## 部署注意事项与最佳实践 1. **运行环境**:`engines.node` 字段强制 `>=22`,Node 18 与 20 已 EOL,低于此版本会在安装期被 npm 拒绝。资料来源：[package.json:18-20]() 2. **发布包内容**:`files` 字段只包含 `dist/`、`schema/`、`templates/`、`README.md`、`LICENSE`,源码 `src/` 不会进入 npm 包,这意味着用户拿到的始终是编译后的 JS,调试时需配合 source map 或本地 `tsx` 运行。资料来源：[package.json:21-23]() 3. **Token 估算可替换**:`estimateTokens` 使用 `chars/4` 启发式,而非真正的 BPE tokenizer;`context.md` 把"可选的精确 tokenizer (gpt-tokenizer)"列为 Tier 3 议题,若需要按模型精确计费,可直接替换 `src/core/tokens.ts` 中的单一函数。资料来源：[src/core/tokens.ts:1-12](), [context.md:10-13]() 4. **vendor 文件请勿手改**:每次 `build` 都会覆盖 `CLAUDE.md` 等四个文件,顶部有 `` 标记。规则修改应回到 `.scope/rules/` 下,再 `agenticscope build`。资料来源：[src/core/vendor.ts:18-25]() 5. **发布前自查清单**:本地依次执行 `npm run typecheck`、`npm test`、`npm run build`,再 `agenticscope lint ` 校验目标项目;CI 失败最常见的原因是 `lint` 发现死 fragment 或重复 id——这是 `fragments.ts` 在 0.2.0 中修复的触发器误匹配引发的连锁问题。资料来源：[CHANGELOG.md:11-16]() --- ## See Also - [Read-Only MCP Server & Workspace Tools](#) - [Manifest Schema & Fragment Types](#) - [Token Budget & Pack Resolution](#) --- --- ## Doramagic 踩坑日志 项目：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