仓库定位与角色

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。

插件清单与职责

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

资料来源：.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。

概述与定位

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

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 会修改 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

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 已知演进路线

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 写入与回放的数据流

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

本仓库围绕 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、hooks/_harness_shim.py:1-60。

钩子生命周期与安全门禁

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

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

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

工作流技能：deploy、harness 与 perception

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

1. harness 插件：负责把仓库引导到可部署状态。repo_bootstrap 已参数化，但 deploy 校验面与 deploy 插件的语义存在漂移——Issue #37（T6）正是要把这条链路"去硬编码"，让 harness 在版本升级时不再落后于 deploy。资料来源：hooks/_harness_shim.py:1-60。
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。

扩展点与未来方向

扩展通过"钩子 + 技能 + 插件清单"三层叠加，新功能不必修改核心代码。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 参数形式注入，不影响钩子主链路。整体设计遵循"感知后台化、门禁前台化、技能模块化"的原则。

Pitfall Log / 踩坑日志

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