# https://github.com/astrojones/astrojones 项目说明书

生成时间：2026-07-18 09:35:23 UTC

## 目录

- [仓库与插件概览](#page-overview)
- [Harness MCP 服务器与 repo_* 工具](#page-mcp-server)
- [感知守护进程、记忆与 Serena 集成](#page-memory-perception)
- [安全钩子、工作流技能与扩展](#page-safety-extensibility)

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

## 仓库与插件概览

### 相关页面

相关主题：[Harness MCP 服务器与 repo_* 工具](#page-mcp-server), [安全钩子、工作流技能与扩展](#page-safety-extensibility)

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

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

- [README.md](https://github.com/astrojones/astrojones/blob/main/README.md)
- [CHANGELOG.md](https://github.com/astrojones/astrojones/blob/main/CHANGELOG.md)
- [AGENTS.md](https://github.com/astrojones/astrojones/blob/main/AGENTS.md)
- [HANDOVER-2026-07-16-restarbeiten-v2.md](https://github.com/astrojones/astrojones/blob/main/HANDOVER-2026-07-16-restarbeiten-v2.md)
- [.claude-plugin/plugin.json](https://github.com/astrojones/astrojones/blob/main/.claude-plugin/plugin.json)
- [.claude-plugin/marketplace.json](https://github.com/astrojones/astrojones/blob/main/.claude-plugin/marketplace.json)
- [plugins/harness/.claude-plugin/plugin.json](https://github.com/astrojones/astrojones/blob/main/plugins/harness/.claude-plugin/plugin.json)
- [plugins/perception/.claude-plugin/plugin.json](https://github.com/astrojones/astrojones/blob/main/plugins/perception/.claude-plugin/plugin.json)
- [plugins/deploy/.claude-plugin/plugin.json](https://github.com/astrojones/astrojones/blob/main/plugins/deploy/.claude-plugin/plugin.json)
- [plugins/mem/.claude-plugin/plugin.json](https://github.com/astrojones/astrojones/blob/main/plugins/mem/.claude-plugin/plugin.json)
</details>

# 仓库与插件概览

## 仓库定位与角色

`astrojones/astrojones` 是一个 **Claude Code 插件市场仓库**，将多个面向"代理工程化"场景的子插件聚合并对外发布。根目录的 `.claude-plugin/marketplace.json` 描述市场元数据（名称、所有者、插件条目），`.claude-plugin/plugin.json` 则声明本仓库自身作为插件的特性。`README.md` 与 `AGENTS.md` 共同规定了协作者面向代理的工作流程与行为约束；`HANDOVER-*.md` 用于在不同次会话间交接意图与决策。资料来源：[.claude-plugin/marketplace.json:1-40]()；[README.md:1-60]()；[AGENTS.md:1-40]()。

整个仓库采用 **"市场 + 子插件"** 的两级结构：根项目发行聚合版本（当前为 `v3.23.0`），而每个插件目录独立维护自身的语义化版本号、`commands`、`hooks` 与 `MCP servers`，便于单独升级。`CHANGELOG.md` 中的条目（如 `v3.23.0` 引入的 `cognee ↔ claude-mem` 协同）实际描述的是市场层发布，而非单插件升级。资料来源：[CHANGELOG.md:1-30]()；[HANDOVER-2026-07-16-restarbeiten-v2.md:1-50]()。

## 插件清单与职责

市场内至少包含四个并列子插件，各自负责一类运行时职责。下表汇总了它们的核心定位与已知工具面：

| 子插件 | 已知版本 | 核心职责 | 主要 MCP 工具 / 资源 |
| --- | --- | --- | --- |
| `harness` | v3.9.2（与清单一致，无未发提交） | 引导与生命周期：`repo_bootstrap` 等参数化命令，以及 harness 与 deploy 之间的部署校验面 | `repo_bootstrap` 等部署前/部署后流程钩子 |
| `perception` | 与市场同步演进 | "外部感知"快照：分支/HEAD、冲突、CI、外部改动等 | `repo_state`、`repo_verify_changed`、`repo_health` |
| `deploy` | 与市场同步演进 | 部署插件，与 harness 的部署校验面并行存在，需要同步去硬编码（参见 #37） | 部署校验 / 校验面对齐 |
| `mem` | 最新 | 记忆层：`cognee` ↔ `claude-mem` 共存，关闭客户端捕获、按门控触发 recall | 记忆读取/写入 MCP 工具 |

资料来源：[.claude-plugin/marketplace.json:20-80]()；[plugins/harness/.claude-plugin/plugin.json:1-30]()；[plugins/perception/.claude-plugin/plugin.json:1-30]()；[plugins/deploy/.claude-plugin/plugin.json:1-30]()；[plugins/mem/.claude-plugin/plugin.json:1-30]()。

这种划分的要点是 **"工具面与运行时不耦合"**：每个子插件都通过 stdio MCP 服务暴露工具，宿主机是 Claude Code（参见 #36 中提到 harness 是 stdio）。因此 `perception` 当前选择走 Claude Code 钩子而非实验性的 `claude/channel` 推送通道，正是因为 stdio 服务的推送稳定性较差。

## 关键能力面：perception

`perception` 是社区当前投入最高、被讨论最多的子系统。其 v1 能力集合覆盖三类外部信号：

- **分支层信号**：当前分支、HEAD 切换、合并冲突；
- **健康层信号**：可通过 `repo_verify_changed`、`repo_health` 按需触发，背景中已由感知守护进程采样（参见 #35，将两者整合为 `repo_state` 的"强制重算"薄层）；
- **CI 信号**：计划复用 `health._ci_check`（`gh run list`）按间隔轮询，并把最新工作流结论汇入 `repo_state` 与 `UserPromptSubmit` 摘要中（参见 #33）。

"外部改动检测"是 v1 → v2 的明确路线图（#34）：`PostToolUse` 已经把代理编辑过的路径写入 `perception_touched.json`，下一步要对其进行哈希或 mtime 记录，从而在观察器发现代理未触发的变更时主动告警。资料来源：[plugins/perception/README.md 或等同入口:1-80]()；[CHANGELOG.md:1-30]()。

## 演进中的约束与社区关注

从最近的社区议题来看，`harness` 与 `deploy` 之间存在 **"版本对齐 vs 部署校验面漂移"** 的张力：harness 自身无版本漂移、`repo_bootstrap` 已参数化，但 deploy 侧的校验面尚未去硬编码，因此 #37（"T6 — De-hardcode the harness deploy tool"）被列为 P2 且被 T1 阻塞。`perception` 侧则同时推进 #33（CI 折叠）、#34（外部改动）、#35（整合 `repo_state`）、#36（Channels 交付升级，可标志门控）四个相互依赖的小主题。

`mem` 侧的最新交付（PR #42，`v3.23.0`）确立了一条原则：**记忆负责镜像上游、不在客户端二次捕获，并通过门控关闭 recall**，与 `claude-mem` 形成清晰边界。读者应把这些议题视为"市场级路线图"而非单插件待办，因为它们往往横跨多个子插件的协作面。资料来源：[CHANGELOG.md:1-30]()；[HANDOVER-2026-07-16-restarbeiten-v2.md:1-50]()；[AGENTS.md:1-40]()。

---

<a id='page-mcp-server'></a>

## Harness MCP 服务器与 repo_* 工具

### 相关页面

相关主题：[仓库与插件概览](#page-overview), [感知守护进程、记忆与 Serena 集成](#page-memory-perception), [安全钩子、工作流技能与扩展](#page-safety-extensibility)

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

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

- [servers/harness-mcp/README.md](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/README.md)
- [servers/harness-mcp/pyproject.toml](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/pyproject.toml)
- [servers/harness-mcp/repo_agent_harness/server.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/server.py)
- [servers/harness-mcp/repo_agent_harness/cli.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/cli.py)
- [servers/harness-mcp/repo_agent_harness/context.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/context.py)
- [servers/harness-mcp/repo_agent_harness/git.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/git.py)
</details>

# Harness MCP 服务器与 repo_* 工具

## 概述与定位

`harness-mcp` 是 astrojones 项目内的标准 MCP（Model Context Protocol）服务器，Python 包名为 `repo_agent_harness`，当前版本 **v3.9.2**，与 manifest 完全一致、零未发布提交。资料来源：[servers/harness-mcp/pyproject.toml:1-40]()

该服务器通过 **stdio 传输**向 Claude Code 等客户端暴露一组 `repo_*` 前缀工具，覆盖仓库引导、状态自检与 Git 操作三大职责，是感知（perception）子系统的前端入口。其设计目标是：在不引入远程端点、不依赖原生库的前提下，提供确定性的本地仓库操作面。资料来源：[servers/harness-mcp/README.md:1-60]()

## 服务器架构

入口由 `server.py` 通过 MCP SDK 注册 stdio 传输并将命令映射为 tool handler；`cli.py` 负责子命令分发与参数解析；`context.py` 维护会话级仓库根、HEAD 与未提交修改缓存；`git.py` 以子进程方式封装 `git(1)` 命令。资料来源：[servers/harness-mcp/repo_agent_harness/server.py:1-80](), [servers/harness-mcp/repo_agent_harness/cli.py:1-80](), [servers/harness-mcp/repo_agent_harness/context.py:1-60](), [servers/harness-mcp/repo_agent_harness/git.py:1-60]()

```mermaid
flowchart TD
    Client[Claude Code stdio 客户端] -->|JSON-RPC| Server[server.py MCP 注册]
    Server --> CLI[cli.py 子命令解析]
    CLI --> Ctx[context.py 会话状态]
    Ctx --> Git[git.py 子进程封装]
    Git -->|subprocess| Bin[(本地 git(1))]
```

`context.py` 在每次 `repo_bootstrap` 调用时建立基线快照，后续 `repo_state` / `repo_verify_changed` 工具以此为对照读取状态，避免重复扫描。资料来源：[servers/harness-mcp/repo_agent_harness/context.py:50-120]()

## repo_* 工具集

| 工具名 | 类别 | 作用 | 是否写状态 |
|--------|------|------|------------|
| `repo_bootstrap` | 引导 | 初始化仓库上下文，记录根路径与基线 HEAD | 是 |
| `repo_state` | 感知 | 返回当前 HEAD、分支、合并冲突等快照 | 否 |
| `repo_verify_changed` | 校验 | 比对工作区与基线的变更文件列表 | 否 |
| `repo_health` | 健康 | 一次性运行完整性检查（冲突、未跟踪文件等） | 否 |

只有 `repo_bootstrap` 会修改 harness 内部 context 缓存；其余三个工具设计为只读，便于感知守护进程与客户端共享同一数据源，并支持未来的 `repo_state` 整合重构。资料来源：[servers/harness-mcp/repo_agent_harness/server.py:60-160](), [issue #35]()

## 部署与运行

通过 `pyproject.toml` 中声明的 console script（典型名称 `repo-agent-harness`）安装后，可在 Claude Code 的 MCP 配置中以 stdio 方式注册。README 给出了最小启动命令示例，并明确指出 harness **不依赖任何远程服务**，全部操作均在本地仓库内完成。资料来源：[servers/harness-mcp/pyproject.toml:20-40](), [servers/harness-mcp/README.md:1-60]()

## 已知限制与后续工作

- **Channels 推送不可靠**：由于 stdio MCP server 下的实验性 `claude/channel` 推送不稳定（参考 anthropic/claude-code #45563、#36431），事件投递当前依赖 Claude Code hooks；计划在 upstream 修复后引入可选、按标志位开启的 channel 能力。资料来源：[issue #36]()
- **perception 整合**：`repo_verify_changed` 与 `repo_health` 与感知快照存在功能重叠，未来将退化为 `repo_state` 的强制刷新入口。资料来源：[issue #35]()
- **外部编辑检测**：v1 exo-perception 仅覆盖分支切换与合并冲突，未感知"其他进程修改了正在编辑的文件"，计划基于 `perception_touched.json` 的 mtime/hash 比对补齐。资料来源：[issue #34]()
- **CI 状态折叠**：希望复用 `health._ci_check`（`gh run list`）按间隔轮询，将最新 workflow 结论写入 `repo_state` 摘要，使代理不再手动调 CI。资料来源：[issue #33]()
- **deploy 工具去硬编码**：harness 与 deploy 插件的部署校验面存在漂移，T6 已立项修复并被 T1 阻塞，尚未随 release 发布。资料来源：[issue #37]()

---

<a id='page-memory-perception'></a>

## 感知守护进程、记忆与 Serena 集成

### 相关页面

相关主题：[Harness MCP 服务器与 repo_* 工具](#page-mcp-server), [安全钩子、工作流技能与扩展](#page-safety-extensibility)

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

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

- [servers/harness-mcp/repo_agent_harness/perception.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/perception.py)
- [servers/harness-mcp/repo_agent_harness/watcher.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/watcher.py)
- [servers/harness-mcp/repo_agent_harness/mem.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/mem.py)
- [servers/harness-mcp/repo_agent_harness/cognee_client.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/cognee_client.py)
- [servers/harness-mcp/repo_agent_harness/cognee_local.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/cognee_local.py)
- [servers/harness-mcp/repo_agent_harness/cognee_sync.py](https://github.com/astrojones/astrojones/blob/main/servers/harness-mcp/repo_agent_harness/cognee_sync.py)
</details>

# 感知守护进程、记忆与 Serena 集成

## 1. 组件边界与协同目标

harness MCP 服务器在每次仓库级 agent 会话中通过三类互补模块提供"环境稳定 + 上下文持久 + 语义检索"的能力：`perception` 守护进程持续探测仓库外部状态、`mem + cognee_*` 处理记忆读写与索引同步、Serena 集成则把语义代码检索桥接到 agent 的编辑动作。本页只覆盖源码可直接验证的部分，Serena 适配层的内部细节见第 4 节说明。

资料来源：[servers/harness-mcp/repo_agent_harness/perception.py:1-40]()

## 2. 感知守护进程 (Perception Daemon)

### 2.1 仓库状态快照与按需复检

`perception.py` 把分支切换、HEAD 移动、合并冲突等"仓库外生变化"汇总到 `repo_state` 快照；`watcher.py` 则以前台监控方式把事件触发为 LLM 上下文中的提醒。`repo_verify_changed` 与 `repo_health` 是按需触发的复检动词工具，社区演进目标 (#35) 是让 `repo_state` 成为主表层，将前两者收敛为"强制刷新"的薄包装。

资料来源：[servers/harness-mcp/repo_agent_harness/perception.py:50-140](), [servers/harness-mcp/repo_agent_harness/watcher.py:30-110]()

### 2.2 PostToolUse / UserPromptSubmit 联动

`PostToolUse` hook 在工具成功后把受影响的文件路径写入 `perception_touched.json`；`UserPromptSubmit` 在每次提示注入时合并 perception 快照与记忆层回填。社区 #34 计划基于该 touched-set 的 hash 或 mtime 检测"另一个进程改动了我正在编辑的文件"，从而把外部编辑纳入感知。

资料来源：[servers/harness-mcp/repo_agent_harness/perception.py:140-220](), [servers/harness-mcp/repo_agent_harness/watcher.py:120-180]()

### 2.3 已知演进路线

| 议题 | 主要变化 | 影响组件 |
| --- | --- | --- |
| #36 Channels 推送 | stdio 下 `claude/channel` 稳定后切换为推送通道 | delivery |
| #35 收敛合并 | 把 `repo_verify_changed`/`repo_health` 并入 `repo_state` | perception |
| #34 外部编辑 | touched-set + hash/mtime 检测 | perception + watcher |
| #33 CI 折叠 | 定时 `health._ci_check` 写入 digest | perception |

## 3. 记忆层 (mem.py + cognee_*)

### 3.1 双栈记忆共存

v3.23.0 (#42) 引入 claude-mem 与 cognee 两侧共存：`mem.py` 封装 claude-mem 的写入与 recall；`cognee_client.py` / `cognee_local.py` / `cognee_sync.py` 分别负责远程客户端、本地回放与双向同步。两侧互为镜像、关闭客户端侧的捕获、按仓库门控 recall，避免重复消费。

资料来源：[servers/harness-mcp/repo_agent_harness/mem.py:1-80](), [servers/harness-mcp/repo_agent_harness/cognee_client.py:1-70](), [servers/harness-mcp/repo_agent_harness/cognee_local.py:1-60]()

### 3.2 写入与回放的数据流

```mermaid
flowchart LR
  A[PostToolUse] --> B[mem.write]
  A --> C[cognee_sync.enqueue]
  B --> D[(claude-mem)]
  C --> E[(cognee graph)]
  F[UserPromptSubmit] --> G[mem.recall]
  F --> H[cognee.query]
  G --> I[prompt digest]
  H --> I[prompt digest]
```

`cognee_sync.py` 负责把写入事件排队、对账、节流回放到 cognee 图谱；`UserPromptSubmit` 阶段两侧并行 recall，由上层按仓库配置决定是否纳入上下文。

资料来源：[servers/harness-mcp/repo_agent_harness/cognee_sync.py:30-130](), [servers/harness-mcp/repo_agent_harness/mem.py:90-160]()

## 4. Serena 集成与边界说明

本次列出的源码未直接包含 Serena 适配层；Serena 在本仓库语境下作为"语义代码检索后端"，由记忆层通过 cognee 的本地模式 (`cognee_local.py`) 间接消费。Serena 工具调用与 harness MCP 之间的具体桥接不属于本页讨论范围，请参考独立的 Serena 适配模块。

资料来源：[servers/harness-mcp/repo_agent_harness/cognee_local.py:60-130]()

---

<a id='page-safety-extensibility'></a>

## 安全钩子、工作流技能与扩展

### 相关页面

相关主题：[仓库与插件概览](#page-overview), [Harness MCP 服务器与 repo_* 工具](#page-mcp-server), [感知守护进程、记忆与 Serena 集成](#page-memory-perception)

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

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

- [hooks/hooks.json](https://github.com/astrojones/astrojones/blob/main/hooks/hooks.json)
- [hooks/_harness_shim.py](https://github.com/astrojones/astrojones/blob/main/hooks/_harness_shim.py)
- [hooks/pre_tool_use.py](https://github.com/astrojones/astrojones/blob/main/hooks/pre_tool_use.py)
- [hooks/post_tool_use.py](https://github.com/astrojones/astrojones/blob/main/hooks/post_tool_use.py)
- [hooks/session_start.py](https://github.com/astrojones/astrojones/blob/main/hooks/session_start.py)
- [hooks/user_prompt_submit.py](https://github.com/astrojones/astrojones/blob/main/hooks/user_prompt_submit.py)
</details>

# 安全钩子、工作流技能与扩展

本仓库围绕 Claude Code 的 stdio 钩子（hooks）机制构建了一套"感知—拦截—审计"扩展层，用以在每一次工具调用、提示词提交与会话启动时插入安全门禁与上下文注入逻辑。`hooks/hooks.json` 是这套体系的入口清单，声明哪些事件触发哪些 Python 脚本；`hooks/_harness_shim.py` 则作为兼容垫片，统一暴露给上层工作流技能调用。`pre_tool_use.py` 与 `post_tool_use.py` 负责在工具执行前后做权限与状态校验，`user_prompt_submit.py` 把仓库感知快照注入提示词前缀，`session_start.py` 负责初始化环境与缓存目录。资料来源：[hooks/hooks.json:1-80](https://github.com/astrojones/astrojones/blob/main/hooks/hooks.json)、[hooks/_harness_shim.py:1-60](https://github.com/astrojones/astrojones/blob/main/hooks/_harness_shim.py)。

## 钩子生命周期与安全门禁

钩子系统按 Claude Code 的事件序列依次触发：`SessionStart` → `UserPromptSubmit` → `PreToolUse` → `PostToolUse` → `Stop`。每一阶段都对应一个 Python 脚本，stdout 写入的 JSON 可对模型行为做"阻断、改写、追加"三类干预。

- **`session_start.py`**：建立工作目录、写入感知状态文件、加载缓存。该脚本对失败采用"降级而非熔断"的策略——任何感知子系统故障都不应阻断会话启动，仅在日志中标记。资料来源：[hooks/session_start.py:1-120](https://github.com/astrojones/astrojones/blob/main/hooks/session_start.py)。
- **`user_prompt_submit.py`**：把 `repo_state` 摘要、`perception_touched.json` 与 CI 状态拼接到用户提示词前，让模型在回答前就拥有仓库上下文。Issue #33 提议把 CI 结论折入该摘要，从而避免模型主动调用 `gh`。资料来源：[hooks/user_prompt_submit.py:1-150](https://github.com/astrojones/astrojones/blob/main/hooks/user_prompt_submit.py)。
- **`pre_tool_use.py`**：是安全门禁的核心。对 `Bash` 命令做黑名单/白名单匹配（例如禁止 `rm -rf /`、强制 `--no-verify` 之外的破坏性 git 操作），对 `Edit`/`Write` 限制在仓库根之内，并在感知层检测到外部进程修改了"我正编辑的文件"时返回"deny + 提示重新读取"。Issue #34 即描述此外部编辑检测的扩展方向。资料来源：[hooks/pre_tool_use.py:1-200](https://github.com/astrojones/astrojones/blob/main/hooks/pre_tool_use.py)。
- **`post_tool_use.py`**：记录已编辑路径到 `perception_touched.json`，并对返回结果做脱敏（例如遮蔽 `Authorization` 头）。资料来源：[hooks/post_tool_use.py:1-180](https://github.com/astrojones/astrojones/blob/main/hooks/post_tool_use.py)。

下表概述四个核心钩子的职责、产出与典型失败模式。

| 钩子脚本 | 触发时机 | 主要职责 | 关键产出 |
|---|---|---|---|
| `session_start.py` | 会话开始 | 初始化感知层、缓存目录 | `repo_state.json` |
| `user_prompt_submit.py` | 用户提交提示词 | 注入仓库感知摘要 | additionalContext |
| `pre_tool_use.py` | 工具调用前 | 权限校验、外部编辑检测 | deny / allow JSON |
| `post_tool_use.py` | 工具调用后 | 记录触摸集、结果脱敏 | `perception_touched.json` |

## 工作流技能：deploy、harness 与 perception

钩子之上是"工作流技能"，它们通过 `_harness_shim.py` 暴露给模型调用。仓库目前存在三个并列的技能面：

1. **harness 插件**：负责把仓库引导到可部署状态。`repo_bootstrap` 已参数化，但 deploy 校验面与 deploy 插件的语义存在漂移——Issue #37（T6）正是要把这条链路"去硬编码"，让 harness 在版本升级时不再落后于 deploy。资料来源：[hooks/_harness_shim.py:1-60](https://github.com/astrojones/astrojones/blob/main/hooks/_harness_shim.py)。
2. **deploy 插件**：执行实际部署校验。harness 与 deploy 的版本通过 `repo_bootstrap` 字段对齐，差异会在 `user_prompt_submit` 的摘要中以警告形式呈现。
3. **perception 插件**：以守护进程方式维护 `repo_state`、`perception_touched.json` 与 CI 缓存。Issue #35 提议把 `repo_verify_changed` / `repo_health` 收敛为 `repo_state` 的强制刷新入口，从而消除重复检查。资料来源：[hooks/hooks.json:1-80](https://github.com/astrojones/astrojones/blob/main/hooks/hooks.json)。

## 扩展点与未来方向

扩展通过"钩子 + 技能 + 插件清单"三层叠加，新功能不必修改核心代码。Issue #36 提出的 Channels 投递升级在落地时，会以"标志位门控的可选能力"形式注册到 `hooks.json`，由 `pre_tool_use.py` 在 MCP stdio 推送稳定后切换通道。`post_tool_use.py` 写入的触摸集哈希将是外部编辑检测（Issue #34）的数据来源，CI 轮询（Issue #33）则会复用 `health._ci_check` 的现有实现。

社区当前最关心的"记忆子系统共存"已在 v3.23.0 落地（PR #42，cognee ↔ claude-mem 镜像、客户端抓取移除、召回门控），其开关以 skill 参数形式注入，不影响钩子主链路。整体设计遵循"感知后台化、门禁前台化、技能模块化"的原则。

---

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

---

## Doramagic 踩坑日志

项目：astrojones/astrojones-mcp-retrieval

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

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

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

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

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

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

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

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

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

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

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

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

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

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

<!-- canonical_name: astrojones/astrojones-mcp-retrieval; human_manual_source: deepwiki_human_wiki -->