rac-core 项目说明书

Doramagic 项目包 · 项目说明书

rac-core 项目

基于 mcp-name 协议 io.github.tcballard/lore 的 RAC 核心模块，为相关功能提供核心实现支持。

Overview and Core Concepts

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

章节 相关页面

继续阅读本节完整说明和来源证据。

项目定位与核心理念

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

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

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

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

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

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

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

另一侧的 agent_rules.py 则把"已 settled 决策"的摘要以 managed block 形式注入代理上下文，确保代理不会在 PR 中偷偷推翻已 Accepted 的决策。资料来源：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

仓库拓扑收敛。 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

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

Architecture and Engine Components

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

章节 相关页面

继续阅读本节完整说明和来源证据。

架构与引擎组件

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)。

架构数据流

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 — 项目总览与快速上手
examples/claude-code/README.md — 与 Claude Code 集成的两套面（推送 + 拉取）
ADR-002 / ADR-007 / ADR-030 / ADR-067 — 决定本架构"确定性 / 契约 / 工具面"的关键决策记录

来源：https://github.com/itsthelore/rac-core / 项目说明书

Agent Integration, MCP Server, and Authoring Workflows

RAC（Requirements as Code）通过两条互补的通道把仓库里"已敲定的决策"交付给 AI 代理：推送（AGENTS.md / CLAUDE.md 等托管上下文文件）与拉取（lore MCP 服务提供的只读工具）。两条通道的目的都在于让代理"引用已接受的决策"而非"重新发明"它们资料来源：[README.md:1-40]()。整个执行引擎是确定性的——不调用...

章节 相关页面

继续阅读本节完整说明和来源证据。

代理集成、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 同时强制两层约束：禁止任何写能力服务的导入，禁止重复实现解析/解析后的解析逻辑。

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 仓库由四条命令组合完成：

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

Release Engineering, Repository Topology, and Ecosystem

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

章节 相关页面

继续阅读本节完整说明和来源证据。

Release Engineering、Repository Topology 与 Ecosystem

版本工程：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 发行版的零迁移原则一脉相承。

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 服务器作为共享成员，使五只只读工具对所有协作者立即可用。

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

Git 钩子（任何客户端）：rac hook install --style pre-commit 在提交时验证暂存区的 RAC 制品；--style post-commit 仅作节奏提示、不阻断。
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 既把"知识制品 + 代理读取面"作为一等公民落地到仓库，又在拓扑、版本与生态之间保持了清晰一致的对外契约。

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

medium 来源证据：repo-topology: rac-sdk — consolidate rac-sdk-ts into rac-sdk/ts/

可能增加新用户试用和生产接入成本。

medium 可能修改宿主 AI 配置

安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。

medium 能力判断依赖假设

假设不成立时，用户拿不到承诺的能力。

medium 来源证据：repo-topology: rac-ci — consolidate rac-actions + lore-watchkeeper + lore-gatekeeper

可能增加新用户试用和生产接入成本。

Pitfall Log / 踩坑日志

项目：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

来源：Doramagic 发现、验证与编译记录

rac-core 项目

Overview and Core Concepts

项目定位与核心理念

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

MCP 读取面与代理引导

企业演进与仓库拓扑

See Also

Architecture and Engine Components

架构与引擎组件

1. 总体定位与设计原则

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

3. 服务层 `rac.services`

4. MCP 服务端与消费边界

架构数据流

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

另请参阅

Agent Integration, MCP Server, and Authoring Workflows

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

概述与定位

MCP 服务：只读工具面

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

客户端集成：Claude Code 与 Codex

信任边界与失败模式

See Also

Release Engineering, Repository Topology, and Ecosystem

Release Engineering、Repository Topology 与 Ecosystem

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

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

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

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

See Also

失败模式与踩坑日记

Pitfall Log / 踩坑日志

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

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

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

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

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

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

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

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

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