# https://github.com/itsthelore/rac-core 项目说明书

生成时间：2026-06-29 07:05:42 UTC

## 目录

- [Overview and Core Concepts](#page-1)
- [Architecture and Engine Components](#page-2)
- [Agent Integration, MCP Server, and Authoring Workflows](#page-3)
- [Release Engineering, Repository Topology, and Ecosystem](#page-4)

<a id='page-1'></a>

## Overview and Core Concepts

### 相关页面

相关主题：[Architecture and Engine Components](#page-2), [Agent Integration, MCP Server, and Authoring Workflows](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/itsthelore/rac-core/blob/main/README.md)
- [src/rac/services/inspect.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/inspect.py)
- [src/rac/services/improve.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/improve.py)
- [src/rac/services/ingest.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/ingest.py)
- [src/rac/services/index.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/index.py)
- [src/rac/services/relationships.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/relationships.py)
- [src/rac/services/export.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/export.py)
- [src/rac/services/stats.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/stats.py)
- [src/rac/services/agent_rules.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/agent_rules.py)
- [src/rac/mcp/server.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/mcp/server.py)
- [rac-localview/src/landing/LandingApp.tsx](https://github.com/itsthelore/rac-core/blob/main/rac-localview/src/landing/LandingApp.tsx)
- [rac-localview/src/viewer/types.ts](https://github.com/itsthelore/rac-core/blob/main/rac-localview/src/viewer/types.ts)
</details>

# Overview and Core Concepts

## 项目定位与核心理念

RAC（Requirements as Code）是一个面向仓库的"需求即代码"确定性引擎。它把**键入式 Markdown** 作为知识制品的物理载体，统一存放在版本控制下的仓库内，强调三件事：

- **键入式 Markdown，就放在仓库里。** 每件制品都是带有最小 frontmatter 信封的纯 Markdown；引擎对其进行确定性分类与按 schema 校验。资料来源：[README.md](https://github.com/itsthelore/rac-core/blob/main/README.md)
- **读取时只读，写入时强制。** MCP 服务端只负责读取；写入路径由 `rac validate` 与 `rac gate` 在 CI 守门，信任边界是人类 PR review。资料来源：[README.md](https://github.com/itsthelore/rac-core/blob/main/README.md)
- **天生离线。** 引擎不发起任何 LLM 调用也不发网络请求；唯一可能的外发是默认关闭、需经同意的遥测 ping。资料来源：[README.md](https://github.com/itsthelore/rac-core/blob/main/README.md)

按公开 Landing 的描述，RAC 当前以 **Lore** 品牌对外展示（MCP 包名为 `lore`），Landing 页明示"Lore 构建在 RAC 之上——引擎开源、对外仍走 `rac` 命名"。资料来源：[rac-localview/src/landing/LandingApp.tsx](https://github.com/itsthelore/rac-core/blob/main/rac-localview/src/landing/LandingApp.tsx)

## 核心架构：服务与读取边界

源码入口 `src/rac/services/` 把职责切成彼此独立、又可被上层组合的薄服务：

```mermaid
flowchart LR
  A["inspect.py<br/>分类与结构读取"] --> E{"组合层"}
  B["improve.py<br/>只读建议"]
  C["ingest.py<br/>外部→Markdown"]
  D["index.py<br/>仓库清单"]
  F["relationships.py<br/>跨制品边"]
  G["stats.py<br/>组合统计"]
  E --> H["export.py<br/>导出 bundle"]
  E --> I["mcp/server.py<br/>只读 MCP 工具"]
```

每个服务都遵循"纯、确定、只读"的契约：

- `inspect` 仅报告分类、置信度、必填/推荐段落；分类委托给 `rac.core.classification`，自身从**不修改内容**也不提建议。资料来源：[src/rac/services/inspect.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/inspect.py)
- `improve` 基于 schema 比对，给出"如何补齐"的引导与 Markdown 模板；不调用 AI、不改写现有内容。资料来源：[src/rac/services/improve.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/improve.py)
- `ingest` 通过 `DocumentConverter` 协议把 DOCX/HTML/PDF 等外部格式转 Markdown，DOCX 走 MarkItDown、`.md` 直接 pass‑through，逻辑独立于 CLI。资料来源：[src/rac/services/ingest.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/ingest.py)
- `index` 单次遍历把发现的制品写入确定性清单，按路径排序，无跨文件解析。资料来源：[src/rac/services/index.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/index.py)
- `relationships` 仅解析 `## Related Decisions`、`## Supersedes` 等规范段落中的引用字符串，不解引用、不校验、不构图；v0.7.0 是纯元数据层。资料来源：[src/rac/services/relationships.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/relationships.py)
- `stats` 按制品族聚合：Requirement 看通过率与计数、Decision 看状态/类别分布，每个族互不污染。资料来源：[src/rac/services/stats.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/stats.py)
- `export` 把以上服务组合成稳定 `CorpusExport` bundle，Portal 等只读查看器按 `VIEWER_CONTRACT.md` v1 消费。资料来源：[src/rac/services/export.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/export.py)

## MCP 读取面与代理引导

`src/rac/mcp/server.py` 是 MCP 服务端的实现，本身是 RAC Core 的**消费者**——它只调用只读服务，绝不重写解析、解析或引用解析。四个核心工具描述按 `guide-tool-surface` 设计钉住（ADR-030）：`get_artifact`、`search_artifacts`、`get_related`、`get_summary`；v0.21.16 又新增 `find_decisions`（ADR-067），用于查询主题下"已 Accepted、尚未退役"的决策。每个工具调用都**重新从磁盘读仓库**——无缓存、无 watcher、无会话状态。资料来源：[src/rac/mcp/server.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/mcp/server.py)

Portal 端的契约由 `rac-localview/src/viewer/types.ts` 锁住：`id`、`aliases`、`type`、`status`、`title`、`path`、`body_html` 字段语义清晰，整套 `Relationship` 边结构也按"from/to"对输出。资料来源：[rac-localview/src/viewer/types.ts](https://github.com/itsthelore/rac-core/blob/main/rac-localview/src/viewer/types.ts)

另一侧的 `agent_rules.py` 则把"已 settled 决策"的摘要以 managed block 形式注入代理上下文，确保代理不会在 PR 中偷偷推翻已 Accepted 的决策。资料来源：[src/rac/services/agent_rules.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/agent_rules.py)

## 企业演进与仓库拓扑

**包重命名。** 最新发布 RAC 2026.06.5 "rename" 把 PyPI 分发包名改成 `rac-core`（原 `requirements-as-code`）；但 `import rac` 与 `rac` CLI 都不变，老脚本与 CI 不受影响。伴随这次 cut，第一波企业级特性以"opt‑in、default‑off"形式进入 RAC。资料来源：[README.md](https://github.com/itsthelore/rac-core/blob/main/README.md)

**仓库拓扑收敛。** Issue #228（ADR‑092）推动若干历史独立仓库并入 `rac-core` 顶层命名空间下的子目录，对应的子任务包括 #238~#242：

| 子任务 | 现状仓库 | 目标位置 |
| --- | --- | --- |
| #242 | `itsthelore/lore-vscode` | `rac-editors/vscode/` |
| #241 | `itsthelore/decisiongrounding` | `rac-benchmarks/` 子目录重组 |
| #240 | `itsthelore/rac-sdk-ts` | `rac-sdk/ts/` |
| #239 | `itsthelore/lore-connectors` | `rac-connectors/<integration>/` |
| #238 | `rac-actions` + `lore-watchkeeper` + `lore-gatekeeper` | `rac-ci/` 整合 |

资料来源：[README.md](https://github.com/itsthelore/rac-core/blob/main/README.md)

这套"命名空间收敛"是社区当前最显眼的推进线，每个子任务均为独立 ADR 跟踪。要点在于：对外命令行、MCP 工具面、viewer 契约都保持稳定，迁移只发生在工程拓扑层面。

## See Also

- [Artifacts（按类型划分的 schema）](/wiki/artifacts)
- [Relationships（跨制品引用的元数据）](/wiki/relationships)
- [Export & Portal 契约](/wiki/export-portal)
- [MCP 工具面与代理引导](/wiki/mcp-agent)

---

<a id='page-2'></a>

## Architecture and Engine Components

### 相关页面

相关主题：[Overview and Core Concepts](#page-1), [Agent Integration, MCP Server, and Authoring Workflows](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/rac/services/inspect.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/inspect.py)
- [src/rac/services/improve.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/improve.py)
- [src/rac/services/ingest.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/ingest.py)
- [src/rac/services/index.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/index.py)
- [src/rac/services/stats.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/stats.py)
- [src/rac/services/export.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/export.py)
- [src/rac/services/relationships.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/relationships.py)
- [src/rac/services/agent_rules.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/agent_rules.py)
- [src/rac/mcp/server.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/mcp/server.py)
- [README.md](https://github.com/itsthelore/rac-core/blob/main/README.md)
</details>

# 架构与引擎组件

## 1. 总体定位与设计原则

RAC（Requirements-as-Code，现以 `rac-core` 名称分发）是一个确定性的 Markdown 知识工件引擎，其核心使命是把仓库内的"类型化 Markdown + YAML 围栏"解析为结构化的 `Product` AST，再据此提供分类、校验、关系抽取与只读查询服务。引擎本身**不调用 LLM、不发起网络请求**，所有处理均为本地、纯函数、可重放（ADR-002），唯一可选外发是一个默认关闭、内容为空的使用率 ping ([README.md:48-50]())。

整体设计遵循"**一次解析、多次复用**"的层次：底层的 `rac.core` 完成解析与分类；中层的 `rac.services` 把这些原语组装成 CLI 与 MCP 可调用的服务（如 `inspect`、`improve`、`index`、`stats`、`export`、`relationships`、`ingest`、`agent_rules`）；外层的 `rac.mcp.server` 仅作为只读消费者，不重新实现任何解析或关系逻辑 ([src/rac/mcp/server.py:8-12]())。

## 2. 核心引擎层 `rac.core`

核心层面向"单一文档"或"语料库遍历"两种粒度，向上提供统一的数据契约：

- **Markdown 解析**：所有 `.md` 进入引擎后统一解析为 `Product` AST，分类、校验、统计都建立在这一中间表示之上，避免各自重复解析（REQ-001）。
- **分类器**：根据 `ArtifactSpec` 把文档判定为 `requirement` / `decision` / `roadmap` / `prompt` / `design` / `unknown`，并报告 0–1 的置信度，是后续所有分析（improve、stats、export）的输入 ([src/rac/services/inspect.py:13-19]())。
- **工件规范**：每种类型声明 `expected`、`optional`、`metadata` 与 `guidance` 字段，`improve` 仅在 `expected` 中每个小节都具备 `guidance` 时才声明"可改进" ([src/rac/services/improve.py:18-25]())。
- **语料库遍历**：`walk_corpus` 是引擎对目录的唯一入口，聚合 `parse` + `classify` + `identify`，供 `inspect`、`index`、`stats`、`export` 共用。

这种分层让"分类逻辑只此一家"，新功能（例如未来的 `rac normalize`）只需复用 `walk_corpus` 即可，无需重复造轮子 ([src/rac/services/inspect.py:11-15]())。

## 3. 服务层 `rac.services`

服务层是 CLI 命令与 MCP 工具的"业务逻辑层"，每个服务对应一条用户可见的能力：

| 服务 | 命令 | 职责 | 关键约束 |
|---|---|---|---|
| `inspect` | `rac inspect <file\|dir>` | 单文档类型识别 + 节缺失诊断；目录时聚合计数 | 仅观察、不修改、不推荐改写 ([src/rac/services/inspect.py:7-9]()) |
| `improve` | `rac improve <file>` | 基于 schema 的"还缺什么 + 怎么补"提示 | 只读、无 AI、不生成正文，仅占位模板 ([src/rac/services/improve.py:7-13]()) |
| `index` | `rac index <dir>` | 输出仓库清单（id / type / title / path） | 单次遍历、确定性、sorted-path 输出 ([src/rac/services/index.py:9-18]()) |
| `stats` | `rac stats <dir>` | 组合层面的指标聚合（feature 计数、决策状态分布等） | 按类型分别聚合，避免互相污染 ([src/rac/services/stats.py:7-13]()) |
| `relationships` | `rac relationships <dir>` | 抽取并解析跨工件引用（related / supersedes / related tickets） | 仅做元数据层；不验证、不构图（v0.7.0）([src/rac/services/relationships.py:7-15]()) |
| `export` | `rac export <dir>` | 生成 Portal HTML / OKF / JSONL / 图谱等外部消费产物 | 确定性、契约化（ADR-007）([src/rac/services/export.py:7-15]()) |
| `ingest` | `rac ingest <file>` | DOCX/HTML/PDF → Markdown 转换 | 通过 `DocumentConverter` 协议注册新来源 ([src/rac/services/ingest.py:7-13]()) |
| `agent_rules` | `rac export --agent-rules` | 把已落定决策写入 `CLAUDE.md` 托管块 | 通过 BEGIN/END 标记做漂移检测 ([src/rac/services/agent_rules.py:9-15]()) |

所有服务都共享同一套"只读、确定性、契约稳定"的工程纪律（REQ-004、ADR-002、ADR-007），并在 `to_dict()` / `supported` / `closest_type` 等字段上保持 JSON 输出的向后兼容。

## 4. MCP 服务端与消费边界

`rac.mcp.server` 是把上述服务暴露给 AI 代理的**只读门面**：注册 `get_artifact`、`search_artifacts`、`get_related`、`get_summary` 四件套（来自 `guide-tool-surface` 设计，描述逐字固定 — ADR-030），并在 v0.21.16 增加 `find_decisions` 用于"团队已决议查询"（ADR-067）。每次调用都重新从磁盘读取仓库（ADR-032），无缓存、无文件监听、无会话状态；相同字节的仓库 + 相同输入 → 相同输出 ([src/rac/mcp/server.py:14-25]())。

边界上，MCP 工具从不重新实现解析或关系抽取，只把 Core 服务的返回值整形到线协议；失败以结构化错误数据返回，不抛协议异常（ADR-034）；隔离性由 `tests/test_mcp_isolation.py` 强制保障 ([src/rac/mcp/server.py:20-25]())。

## 架构数据流

```mermaid
flowchart LR
    A[仓库 Markdown] --> B[rac.core<br/>parse + classify]
    B --> C[rac.services<br/>inspect/improve/index/<br/>stats/relationships/export]
    C --> D[rac CLI]
    C --> E[rac mcp.server<br/>只读工具]
    E --> F[AI 代理<br/>Claude Code / Cursor ...]
    C --> G[rac-localview<br/>Portal / 图谱]
    A -. ingest .-> H[DocumentConverter<br/>DOCX/HTML/PDF]
    H --> A
```

## 5. 常见失效模式与设计边界

- **不支持的工件类型**：`improve` 在 spec 缺少 `guidance` 时返回 `supported=false`（[src/rac/services/improve.py:18-25]()），`export` 在 `unknown` 上直接跳过（[src/rac/services/export.py:43-46]()）—— 二者都不会强行输出，而是显式让调用方知道边界。
- **跨工件引用**：v0.7.0 的 `relationships` 仅做元数据抽取，不解析、不校验、不构图；真正的图遍历交给 `rac mcp get_related`（[src/rac/services/relationships.py:7-15]()）。
- **可观测的契约**：所有服务的 `to_dict()` 都是 ADR-007 公共契约，新增字段须为可加（`relationships`、`status` 等仅在存在时出现）。

## 另请参阅

- [README.md](https://github.com/itsthelore/rac-core/blob/main/README.md) — 项目总览与快速上手
- [examples/claude-code/README.md](https://github.com/itsthelore/rac-core/blob/main/examples/claude-code/README.md) — 与 Claude Code 集成的两套面（推送 + 拉取）
- ADR-002 / ADR-007 / ADR-030 / ADR-067 — 决定本架构"确定性 / 契约 / 工具面"的关键决策记录

---

<a id='page-3'></a>

## Agent Integration, MCP Server, and Authoring Workflows

### 相关页面

相关主题：[Architecture and Engine Components](#page-2), [Release Engineering, Repository Topology, and Ecosystem](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/rac/mcp/server.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/mcp/server.py)
- [README.md](https://github.com/itsthelore/rac-core/blob/main/README.md)
- [examples/claude-code/README.md](https://github.com/itsthelore/rac-core/blob/main/examples/claude-code/README.md)
- [examples/codex/README.md](https://github.com/itsthelore/rac-core/blob/main/examples/codex/README.md)
- [examples/obey-demo/README.md](https://github.com/itsthelore/rac-core/blob/main/examples/obey-demo/README.md)
- [src/rac/services/agent_rules.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/agent_rules.py)
- [src/rac/services/index.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/index.py)
- [src/rac/services/improve.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/improve.py)
- [src/rac/services/relationships.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/relationships.py)
</details>

# 代理集成、MCP 服务与创作工作流

## 概述与定位

RAC（Requirements as Code）通过两条互补的通道把仓库里"已敲定的决策"交付给 AI 代理：**推送**（`AGENTS.md` / `CLAUDE.md` 等托管上下文文件）与**拉取**（`lore` MCP 服务提供的只读工具）。两条通道的目的都在于让代理"引用已接受的决策"而非"重新发明"它们 资料来源：[README.md:1-40]()。整个执行引擎是确定性的——不调用任何 LLM，不发起网络请求，只对外暴露一个许可可控、内容为空的使用埋点 资料来源：[README.md:18-30]()。

整个集成的核心契约由 ADR-030（工具描述）、ADR-032（每次重读，无缓存）、ADR-034（失败以结构化错误返回，绝不抛协议异常）共同定义。`rac mcp` 命令构建的 FastMCP 应用就是这一契约的载体。

## MCP 服务：只读工具面

`lore` MCP 服务以 `rac mcp --root <repo>` 启动后，注册五个只读工具。它们的服务实现分别落在 RAC Core 的对应模块里：解析、识别、分类、关系抽取与决策检索全部由核心服务承担，MCP 层只做装配 资料来源：[src/rac/mcp/server.py:1-35]()。

| 工具 | 用途 | 服务来源 |
|---|---|---|
| `get_summary` | 仓库决策地图 | 组合 `index` + `relationships` |
| `search_artifacts` | 按自然语言检索决策 | `rac.services.find`（共享匹配） |
| `get_artifact` | 按 ID 拉取完整记录 | `rac.core.identity` + `parse_file` |
| `get_related` | 沿有向图遍历关联 | `rac.services.relationships` |
| `find_decisions` | 检索某主题下已 Accepted、未退役的决策（ADR-067） | `rac.services.decisions` |

服务**每次调用都从磁盘重读仓库**：没有缓存、没有文件监听、没有会话状态——同一字节、同一入参、同一响应（在每响应字符预算内，ADR-033） 资料来源：[src/rac/mcp/server.py:30-50]()。隔离测试 `tests/test_mcp_isolation.py` 同时强制两层约束：禁止任何写能力服务的导入，禁止重复实现解析/解析后的解析逻辑。

```mermaid
flowchart LR
    A[代理: Claude/Codex/Cursor] -->|MCP stdio| B[lore 服务<br/>rac mcp --root .]
    B --> C[rac.services.find]
    B --> D[rac.services.index]
    B --> E[rac.services.relationships]
    B --> F[rac.services.decisions<br/>find_decisions]
    C --> G[(rac/ Markdown<br/>知识语料)]
    D --> G
    E --> G
    F --> G
    A -.推送.-> H[AGENTS.md / CLAUDE.md<br/>rac export --agent-rules]
    H --> G
```

## 创作工作流：导入、检查与改进

把现有知识迁入 RAC 仓库由四条命令组合完成：

1. **导入**：`rac new <type>` 根据类型规范（`ArtifactSpec`）生成带前页信息的脚手架；多格式或批量场景则使用 `rac-ingest` 技能，由 `rac.services.ingest` 的 `DocumentConverter` 协议把 DOCX（未来支持 HTML/PDF）转换为 Markdown——转换只保留结构，**不评判**产物是否合规 资料来源：[src/rac/services/ingest.py:1-20]()。
2. **检查**：`rac inspect <file>` 报告类型、置信度与缺失段落；目录模式聚合类型计数。分类完全委托给 `rac.core.classification`，关系抽取委托给 `rac.services.relationships`（ADR-016：跨制品引用走 `## Related Decisions` 等显式段落） 资料来源：[src/rac/services/relationships.py:1-25]()。
3. **改进**：`rac improve <file>` 是只读、确定性的"建议"能力——只比对类型规范中的 `expected` 段与 `guidance` 字段，提示作者补什么、按什么写法补；它**不调用 AI、不重写内容**，且仅当类型具备完整指导时可用 资料来源：[src/rac/services/improve.py:1-20]()。
4. **仓库清单**：`rac index` 一次遍历产出确定性清单（稳定 ID、类型、标题、路径），供 Explorer、IDE、CI 等消费者构建导航——它刻意不做校验、不打分、不解析元数据 资料来源：[src/rac/services/index.py:1-25]()。

## 客户端集成：Claude Code 与 Codex

两条通道在 Claude Code 中以"托管 `CLAUDE.md` + `lore` MCP"形式呈现。`rac export rac/ --agent-rules` 把已接受决策写入仓库根的 `CLAUDE.md` 受管块，外侧用户内容**逐字节保留**；`--check` 模式让 CI 在漂移时直接失败 资料来源：[src/rac/services/agent_rules.py:1-35]()。MCP 服务则通过 `claude mcp add lore -- rac mcp` 或项目级 `.mcp.json` 注册，暴露上述五个只读工具 资料来源：[examples/claude-code/README.md:1-50]()。

Codex 走同样的双通道：`AGENTS.md` 由 `--agent-rules` 生成，MCP 服务在 `config.toml` 中以 `[mcp_servers.lore]` 表挂载 资料来源：[examples/codex/README.md:1-35]()。Claude Code 额外提供 `rac skill install rac-artifacts`（指导代理用 `rac` CLI 创建/校验/更新制品，**仅触及 `rac/` 子树**），以及一个"编辑前否决"钩子——它是 RAC 唯一允许在编辑窗口前置拦截的平台 资料来源：[examples/claude-code/README.md:60-80]()。

`examples/obey-demo/` 是验证"接地行为"的标准用例：连接 `lore` 后，代理在编写代码前会先 `search_artifacts`（例如以 `delete user`），命中 `ADR-001` 后 `get_artifact` 读出硬 `DELETE` 禁令，并引用其 ID 给出软删除替代方案——整个推理链机械可复现 资料来源：[examples/obey-demo/README.md:1-40]()。

## 信任边界与失败模式

- **只读契约**：`lore` 服务不导入任何写能力服务，隔离测试强制该约束 资料来源：[src/rac/mcp/server.py:20-40]()。
- **失败语义**：查找失败以结构化错误返回而非协议异常，代理可据此恢复（ADR-034）。
- **编辑时机**：除 Claude Code 的 `PreToolUse` 钩子外，RAC 的强制点均在"编辑后"——`rac validate` / `rac gate` 在 CI 中阻断畸形制品、断链与指向已取代决策的引用 资料来源：[README.md:25-35]()。
- **企业开关**：遥测默认关闭，`rac telemetry off --enterprise` 可证明受监管安装中埋点不会触发（ADR-086）。

## See Also

- [CLI 参考](https://itsthelore.github.io/rac-core/cli/)：所有 `rac` 子命令与选项。
- [安全态势](docs/security.md)：ADR-086 的企业开关与隔离约束详解。
- [仓库工作流](docs/repo-workflow.md)：PR 评审、`rac gate` 与受管块更新流程。

---

<a id='page-4'></a>

## Release Engineering, Repository Topology, and Ecosystem

### 相关页面

相关主题：[Overview and Core Concepts](#page-1), [Agent Integration, MCP Server, and Authoring Workflows](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/itsthelore/rac-core/blob/main/README.md)
- [src/rac/mcp/server.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/mcp/server.py)
- [src/rac/services/ingest.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/ingest.py)
- [src/rac/services/export.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/export.py)
- [src/rac/services/portfolio.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/portfolio.py)
- [src/rac/services/agent_rules.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/services/agent_rules.py)
- [src/rac/explorer/widgets/statusline.py](https://github.com/itsthelore/rac-core/blob/main/src/rac/explorer/widgets/statusline.py)
- [examples/claude-code/README.md](https://github.com/itsthelore/rac-core/blob/main/examples/claude-code/README.md)
- [rac-localview/src/demo/DemoApp.tsx](https://github.com/itsthelore/rac-core/blob/main/rac-localview/src/demo/DemoApp.tsx)
- [rac/roadmaps/repo-topology/rac-editors.md](https://github.com/itsthelore/rac-core/blob/main/rac/roadmaps/repo-topology/rac-editors.md)
- [rac/roadmaps/repo-topology/rac-ci.md](https://github.com/itsthelore/rac-core/blob/main/rac/roadmaps/repo-topology/rac-ci.md)
- [rac/roadmaps/repo-topology/rac-connectors.md](https://github.com/itsthelore/rac-core/blob/main/rac/roadmaps/repo-topology/rac-connectors.md)
- [rac/roadmaps/repo-topology/rac-sdk.md](https://github.com/itsthelore/rac-core/blob/main/rac/roadmaps/repo-topology/rac-sdk.md)
- [rac/roadmaps/repo-topology/rac-benchmarks.md](https://github.com/itsthelore/rac-core/blob/main/rac/roadmaps/repo-topology/rac-benchmarks.md)
</details>

# Release Engineering、Repository Topology 与 Ecosystem

本页围绕 RAC 项目的发布工程、仓库拓扑与生态三方面，勾勒出从版本节奏、命名收敛到下游集成的全景视图。所有论述基于仓库源码与社区跟踪中的路线图文档。

## 版本工程：2026.06.5 "rename" 发行版

RAC 采用"日期式"语义版本号（如 `2026.06.5`），每一发行版都附带明确的设计意图。最新一期 `2026.06.5` 被定位为 *rename* 发行版：PyPI 发行版名称由 `requirements-as-code` 改为 `rac-core`，但 Python 导入包名 `rac` 与 CLI 可执行名 `rac` 保持不变，从而保证现有脚本、CI 与下游集成的零迁移成本。围绕这次重命名，本发行版首次落地了一组企业级采用特性，但全部采用 **opt-in / 默认关闭** 的策略，确保 RAC 在常规部署路径上的行为完全向后兼容。引擎本体依旧保持"气隙"语义：不发起 LLM 调用、不访问网络，唯一对外通信是默认关闭、需显式同意的内容无关使用率遥测。

资料来源：[README.md]()

## 仓库拓扑收敛：ADR-092 与子组织重组

社区正在推进 `repo-topology convergence`（ADR-092）——把当前散落在多个独立 GitHub 仓库的子项目统一归并到 `itsthelore` 组织下的命名空间，按职责分子目录收敛：

| 目标命名空间 | 来源仓库（合并项） |
| --- | --- |
| `rac-editors/vscode/` | `itsthelore/lore-vscode` |
| `rac-benchmarks/` | `itsthelore/decisiongrounding`（目录化重构） |
| `rac-sdk/ts/` | `itsthelore/rac-sdk-ts`（非 Python 瘦客户端） |
| `rac-connectors/` | `itsthelore/lore-connectors`（每个集成一个子目录） |
| `rac-ci/` | `itsthelore/rac-actions` + `itsthelore/lore-watchkeeper` + `itsthelore/lore-gatekeeper` |

每个目标仓库对应一个独立的跟踪 issue（#238–#242），并由 `rac/roadmaps/repo-topology/*.md` 子文档描述具体迁移路径。这种"先命名、再代码、再 CI"的收敛方式使所有外部仓库的别名、`pip` 包名、CLI 行为得以保留——这与 `2026.06.5` rename 发行版的零迁移原则一脉相承。

```mermaid
flowchart LR
    A[lore-vscode] --> E[rac-editors/vscode/]
    B[decisiongrounding] --> F[rac-benchmarks/]
    C[rac-sdk-ts] --> G[rac-sdk/ts/]
    D[lore-connectors] --> H[rac-connectors/]
    I[rac-actions] --> J[rac-ci/]
    K[lore-watchkeeper] --> J
    L[lore-gatekeeper] --> J
```

## 生态架构：Core、MCP、Explorer、Portal

RAC 的运行时由四个相互隔离的关注点组成，并通过显式的服务接口拼接：

- **Core（Python 引擎）**：在仓库根目录被 `pip install -e .[dev]` 安装，对外暴露 `rac` CLI；不依赖 LLM，也不发网络请求。
- **MCP Server**：通过 `rac mcp` 启动，绑定仓库根并注册一组只读工具（`get_artifact`、`search_artifacts`、`get_related`、`get_summary`，以及 `v0.21.16` 新增的 `find_decisions`）。每次工具调用都重新读取仓库，无缓存、无文件监听、无会话状态——相同输入一定得到相同输出。服务器仅作为 Core 的消费者存在，不重新实现解析、关系抽取或评分，也不导入任何具备写能力的服务。
- **Explorer**：基于 Textual 的 TUI 浏览器，含底部状态行的键位提示与健康度显示。
- **Portal**：由 `rac export` 输出的 `CorpusExport` 数据驱动的只读 HTML/图谱查看器。导出在 Core 中实现，承诺字节级确定性，并以公开契约形式锁定 `status`、`title`、`body_html` 等字段语义。

服务之间的边界由 ADR-015 / ADR-031 / ADR-032 严格划定：MCP Server 仅作为 Core 的消费者；Portal 接收的 Markdown 在进入渲染前会被显式关闭原始 HTML 输出，以保证"制品本身与查看器无关"。

资料来源：[src/rac/mcp/server.py]()、[src/rac/services/export.py]()、[src/rac/explorer/widgets/statusline.py]()

## 集成触点：代理、IDE、CI 与规则注入

RAC 在客户端的接入遵循"上下文按需拉取、写入人工把关"的模式。Claude Code 的典型接入只需一行命令 `claude mcp add lore -- rac mcp --root .`；团队也可以提交项目级 `.mcp.json` 把 `lore` MCP 服务器作为共享成员，使五只只读工具对所有协作者立即可用。

写入侧的约束由两类钩子承担：

1. **Git 钩子（任何客户端）**：`rac hook install --style pre-commit` 在提交时验证暂存区的 RAC 制品；`--style post-commit` 仅作节奏提示、不阻断。
2. **PreToolUse 钩子（仅 Claude Code）**：在编辑动作真正落地前做一次否决式校验。

`rac skill install rac-artifacts` 把"作者技能"注入客户端本地工程目录，使其知晓如何用 `rac` 命令创建、校验与更新制品；可选技能还包括 `rac-import`、`rac-ingest`、`rac-review`。与此同时，`rac agent-rules` 通过 BEGIN/END 标记管理的代码块把已落定决策的摘要内联进源文件，由 `--check` 漂移门控保证摘要与制品保持一致。

文档转换入口 `rac ingest` 走 `DocumentConverter` 协议：`.md` 走零依赖直通的 `MarkdownConverter`，DOCX/PDF/HTML 等富文本则通过可选 `ingest` extra 安装的 `MarkItDownConverter` 转换——新增数据源只需注册新协议，CLI 不变。

资料来源：[examples/claude-code/README.md]()、[src/rac/services/agent_rules.py]()、[src/rac/services/ingest.py]()

通过上述组合，RAC 既把"知识制品 + 代理读取面"作为一等公民落地到仓库，又在拓扑、版本与生态之间保持了清晰一致的对外契约。

## See Also

- RAC MCP Server 与五只只读工具的契约说明（`src/rac/mcp/server.py`）
- 仓库级健康度评分与组合公式（`src/rac/services/portfolio.py`）
- 制品转换（`ingest`）与导出（`export`）的确定性保证
- 社区路线图：`repo-topology convergence`（ADR-092）及 #228 下的子 issue

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：itsthelore/rac-core

摘要：发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：repo-topology: rac-sdk — consolidate rac-sdk-ts into rac-sdk/ts/。

## 1. 安装坑 · 来源证据：repo-topology: rac-sdk — consolidate rac-sdk-ts into rac-sdk/ts/

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：repo-topology: rac-sdk — consolidate rac-sdk-ts into rac-sdk/ts/
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/itsthelore/rac-core/issues/240 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

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

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

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://news.ycombinator.com/item?id=48714880 | README/documentation is current enough for a first validation pass.

## 4. 维护坑 · 来源证据：repo-topology: rac-ci — consolidate rac-actions + lore-watchkeeper + lore-gatekeeper

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：repo-topology: rac-ci — consolidate rac-actions + lore-watchkeeper + lore-gatekeeper
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/itsthelore/rac-core/issues/238 | 来源类型 github_issue 暴露的待验证使用条件。

## 5. 维护坑 · 维护活跃度未知

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

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://news.ycombinator.com/item?id=48714880 | no_demo; severity=medium

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

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://news.ycombinator.com/item?id=48714880 | no_demo; severity=medium

## 8. 安全/权限坑 · 来源证据：Epic: growth programme — adoption of Lore / RAC

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Epic: growth programme — adoption of Lore / RAC
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/itsthelore/rac-core/issues/230 | 来源类型 github_issue 暴露的待验证使用条件。

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

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48714880 | issue_or_pr_quality=unknown

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

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

<!-- canonical_name: itsthelore/rac-core; human_manual_source: deepwiki_human_wiki -->