> ## Documentation Index
> Fetch the complete documentation index at: https://powercontext.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Scope

> 设错 Scope 通常不报错，只是搜不到。

PowerContext 的大部分操作都要求 `scope_id`。它决定这次请求读写哪一组数据。

把 Scope (决定这次请求读写哪一组数据。设错时通常不报错，只是搜不到。) 设错，最常见的结果不是报错，而是明明写过却查不到。更糟的情况是两个本应隔离的项目用了同一个 Scope。

Scope 解析应是应用决策，而不是随手使用的后备值。多租户服务要先通过认证与授权确定允许访问的租户和项目，再把对应的 `scope_id` 交给适配器。

## Scope 隔离什么

同一个 `scope_id` 下，PowerContext 维护一组相互关联的状态。这里有 Source 日志和处理游标，有 Memory 生命周期与启用状态搜索投影，有 Experience 和 Skill 的 Candidate 收件箱，有 Handoff 历史内容与工作连续性，也有 Scope 内部运行时缓存、锁和统计。

另一个 Scope 看不到这些数据，除非应用把同样的内容再次写入。

![Scope 是一堵墙。这边写过，那边看不见。](https://mintcdn.com/powercontext/1t_ajifOEOG5YQjP/assets/mental-scope-wall-zh.svg?fit=max\&auto=format\&n=1t_ajifOEOG5YQjP\&q=85\&s=9e6360fa19a85a55f44e9d19843e5c1d)

## Scope 不做什么

Scope 不是安全身份。

知道 `scope_id="project:payments"` 不代表调用者属于 payments 团队，也不代表它可以调用写工具。Bearer 令牌、Server 部署边界和宿主权限准入规则负责访问控制。

Scope 也不会授予执行权限。召回结果即使来自正确 Scope，仍然是历史证据。Agent 必须遵守当前系统或用户指令，并检查实时工作区。

> [!WARNING]
>
> 不要把用户可控的字符串直接当成已授权 Scope。先完成身份验证和授权，再由应用决定这个请求可以使用哪个 `scope_id`。

## 选择稳定的 Scope

一个好 Scope 应该随着工作持续存在，而不是随着会话变化。

| 场景 | 推荐 | 不推荐 |
| - | - | - |
| 单个代码仓库 | 规范化的 Git 远程，或显式项目 ID | 临时工作树路径 |
| 多租户服务 | 由已认证租户或项目映射出的显式 Scope | 服务进程的当前目录 |
| 本地无 Git 项目 | 适配器支持时使用稳定路径哈希，或显式 Scope | 每次运行生成随机 ID |
| 跨宿主共享 | 为各宿主配置同一个稳定值 | 使用各自的会话 ID |

Scope 字符串区分大小写。`project:PowerContext` 和 `project:powercontext` 是两个 Scope。

## 没有统一的自动推导顺序

各集成会根据宿主能提供的信息推导 Scope，但策略并不相同。

| 集成 | 当前推导方式 |
| - | - |
| Pydantic AI Agent 适配器 | constructor 字符串或回调，再到环境、规范化的 Git 远程、本地路径哈希 |
| LangGraph | 调用 Scope 或环境，再到规范化的网络 Git 远程，缺失时报错 |
| LangChain | 调用 Scope 或环境，再到规范化的网络 Git 远程，缺失时报错 |
| Codex / Claude Code | Workstream 绑定（适用时）、Git 远程或项目路径。具体顺序以各宿主页为准 |
| OpenClaw | 可信 agent 标识。项目模式还加入项目哈希，但仍保留 agent 维度 |

心智模型只给选择原则。具体优先顺序放在对应适配器页面。不要把某个适配器的后备路径复制到所有宿主。

### Git 远程会先规范化

推导 Scope 时，集成会去掉远程 URL 中的凭证。下面两个地址不应该形成两个项目，也不应该把令牌写进 Scope。

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
https://user:token@example.com/org/repo.git
https://example.com/org/repo.git
```

LangGraph 和 LangChain 会识别 Windows drive-letter 路径，避免把它误判为 SCP 风格远程。其他适配器的保护规则并不一致。在 Windows 或自定义 Git 环境里，优先使用显式 Scope，并检查最终派生值。

## 跨宿主共享

Codex 和 Claude Code 可以对同一仓库推导出相同项目 Scope。这样，一边显式保存的 Memory 可以在另一边召回。

共享成立需要三个条件同时满足。两个宿主连接同一个 PowerContext Server。两边最终得到完全相同的 `scope_id`。读写使用同一套访问授权。

只满足“目录看起来一样”还不够。排查共享问题时，先打印或检查最终 Scope，再看 Memory 搜索。

> [!NOTE]
>
> OpenClaw 的项目模式当前仍把 agent ID 放进 Scope。相同项目、不同 agent 不会自动共享一个纯项目 Scope。

## Server 内的 ScopeCache

Server 为活跃 Scope 缓存运行时组合和一把 Scope 内部写入锁。默认容量是 128 个停用状态条目。

这不是数据缓存。淘汰不会删除数据库中的 Source、Memory 或 Handoff。正在使用或等待同一 Scope 锁的条目不会被驱逐。如果所有条目都处于启用状态，缓存可以暂时超过容量。操作完成后，Server 再清理最久未使用的停用状态条目。

同一 Scope 的写操作需要串行化，以保护头版本和游标更新。只读搜索和已经开始的 rerank 不应全部被这把写锁串行。

## 常见故障

### 写入成功，但 Dashboard 看不到

检查 Dashboard 和客户端使用的 Scope 是否逐字相同。切换数据库 URL 也会让你看到另一套数据，这和 Scope 问题表现相似。逐步对照见[用 Dashboard 核对 Scope 统计](https://powercontext.mintlify.site/zh/basic-usage/dashboard.md)。

### 两个租户看到了同一条 Memory

确认应用没有把服务进程 cwd 或固定字符串当成所有租户的 Scope。Scope 必须来自已经授权的租户或项目映射。

### LangGraph 在本地目录报 MissingScope

LangGraph 不会在缺少网络 Git 远程时自动回退到本地路径哈希。为这次调用提供 `PowerContextScope(scope_id=...)`。

### 每次新会话都像第一次使用

通常是把会话 ID 当成 Scope。改用稳定项目或租户 Scope。

## 怎么知道分清了

1. Scope 稳定，并且不包含凭证。
2. 多租户应用先授权，再选择 Scope。
3. 需要共享的宿主得到完全相同的值。
4. 不要假设所有适配器都有相同后备路径。
5. 缓存淘汰不是持久数据删除。

对不上时，先对[排错](https://powercontext.mintlify.site/zh/start/troubleshooting.md)。接下来读 [fail-open](https://powercontext.mintlify.site/zh/mental-model/fail-open.md)，了解哪些失败可以继续，哪些必须明确报错。

## 下一步

> [card] [再看失败时谁能继续](https://powercontext.mintlify.site/zh/mental-model/fail-open.md)
>
> 自动找回失败时，手头工作还应继续。你明确要求写入时，失败必须看得见。

> [card] [对上最像的那条故障](https://powercontext.mintlify.site/zh/start/troubleshooting.md)
>
> 搜不到、页面是空的，或诊断过了还是不行？先对照已经出现过的情况。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.