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

生成时间：2026-06-25 18:16:36 UTC

## 目录

- [项目概览与系统架构](#page-1)
- [Agent 生命周期、上下文包与工作流](#page-2)
- [内存模型、安全分级与诊断工具](#page-3)
- [Dashboard、Git 同步与 MCP 可观测性](#page-4)

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

## 项目概览与系统架构

### 相关页面

相关主题：[Agent 生命周期、上下文包与工作流](#page-2), [内存模型、安全分级与诊断工具](#page-3), [Dashboard、Git 同步与 MCP 可观测性](#page-4)

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

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

- [README.md](https://github.com/Richardyu114/Moryn/blob/main/README.md)
- [package.json](https://github.com/Richardyu114/Moryn/blob/main/package.json)
- [src/core/agent-identity.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/agent-identity.ts)
- [src/core/autocapture-policy.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/autocapture-policy.ts)
- [src/core/action-safety.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/action-safety.ts)
- [src/core/agent-lifecycle.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/agent-lifecycle.ts)
</details>

# 项目概览与系统架构

## 1. 项目定位与设计目标

Moryn 是一个面向多 Agent、多设备 AI 工作场景的 **本地优先（local-first）、用户拥有、可审计**的上下文存储与交接层。它既不是 Agent 平台，也不是向量记忆 SDK，更不是托管云服务，而是 Agent 之间的「记忆总线」：默认路径简洁，在用户或 Agent 需要审查、溯源、同步或交接历史时完全可追溯。

核心定位来源于 [README.md:1-13]()：

> *"Moryn is a local-first, user-owned, auditable context store and handoff layer for multi-agent, multi-device AI work."*

当前版本为 **v0.1.1**（首个 npm 发布后的补丁版本），主要交付物包括：本地记忆操作、Git 同步、生命周期交接、包级冒烟测试与 stdio MCP 服务。npm 包名为 `@richardyu114/moryn`，安装方式为 `npm install -g @richardyu114/moryn` ([package.json:1-3]())。

## 2. 技术栈与运行时约束

| 维度 | 取值 | 来源 |
|---|---|---|
| 运行时 | Node.js >= 20 | [package.json:53-55]() |
| 语言 | TypeScript（ESM，`"type": "module"`） | [package.json:6]() |
| 核心依赖 | `@modelcontextprotocol/sdk ^1.29.0`、`commander ^14.0.2`、`zod ^4.1.13` | [package.json:39-43]() |
| 测试栈 | `vitest ^4.0.14`、`tsx ^4.21.0` | [package.json:45-51]() |
| 许可证 | MIT | [package.json:56-58]() |
| CLI 入口 | `moryn` → `dist/cli.js`；MCP 注册命令 `moryn mcp` | [README.md:29-37]()、[package.json:9-12]() |

模块组织上，源码位于 `src/`，CLI 与公开库入口分别为 `src/cli.ts` 与 `src/index.ts`，核心领域逻辑集中在 `src/core/` 下（包括 `agent-lifecycle.ts`、`agent-identity.ts`、`autocapture-policy.ts`、`action-safety.ts` 等）。

## 3. 五态记忆模型与敏感数据护栏

Moryn 将所有记录划分为五个生命周期状态，状态转换关系如下：

```mermaid
stateDiagram-v2
    [*] --> raw
    raw --> candidate: 初步入库
    candidate --> canonical: 升级为持久上下文
    candidate --> archived: 归档
    candidate --> quarantined: 隔离
    canonical --> archived: 归档
    canonical --> quarantined: 隔离
```

- **`raw`**：源材料，默认隐藏。
- **`candidate`**：可能有用但尚未信任。
- **`canonical`**：默认召回返回的持久上下文。
- **`archived`**：保留的历史，默认隐藏。
- **`quarantined`**：敏感或不安全内容，默认隐藏 ([README.md:18-30]())。

带 `private`、`secret`、`sensitive` 标签的记录在 `boot`、`recall`、`refresh`、`list-recent`、`timeline`、`memory doctor`、`memory lifecycle`、`capture policy`、`dogfood report` 以及 Dashboard 等读路径上默认排除；仅当显式传入 `--include-private` 或 MCP 参数 `include_private: true` 时才返回。高风险 canonical 写入需要用户显式确认 ([README.md:32-38]())。

## 4. Agent 生命周期与自动化捕获

Agent 操作走「引导—启动—状态—结束—刷新」五阶段生命周期，模块入口为 `src/core/agent-lifecycle.ts`，对应 CLI/MCP 工具为 `agent_enter`、`agent_start`、`agent_status`、`agent_finish` 以及带 `refresh_since` 的 `agent_start` 刷新动作。每一步都返回结构化的 `next.actions` 列表（含 `safe_to_run`、`required_fields`、`command` 模板），驱动 Agent 按机器可读的契约执行 ([src/core/agent-lifecycle.ts:148-160]()、[src/core/agent-lifecycle.ts:317-419]())。

身份归一化在 [src/core/agent-identity.ts:18-23]() 中预定义四类已知 Agent 家族：`codex`、`claude`、`kimi`、`gemini`；其它客户端落入 `generic` 或 `unknown` 等级，便于在多 Agent 场景下追溯来源。

自动捕获策略（`src/core/autocapture-policy.ts`）按风险分级路由：
- **低风险 handoff**：自动写入 `candidate` 态，标签 `auto-captured`，出现在 Dashboard `handoff` 面板，不进入 canonical ([src/core/autocapture-policy.ts:60-78]())。
- **带审查风险标记**：路由到 `capture_inbox`，等待用户批/拒决策 (`review_required: true`、`user_action_required: true`) ([src/core/autocapture-policy.ts:40-58]())。

动作安全层 `src/core/action-safety.ts` 为每个候选动作计算 `safe_to_run`、缺失字段与 runbook，区分 `run` / `collect_required_fields` / `confirm_with_user` / `do_not_auto_run` 四类后续步骤，防止 Agent 误触发本地配置写入或高风险升级 ([src/core/action-safety.ts:1-60]())。

## 5. 架构总览

下图描绘了用户、Agent、CLI/MCP 与本地 Git 存储之间的关系：

```mermaid
flowchart LR
    User[用户/多设备] -->|决策| Dashboard[moryn dashboard]
    Codex[Codex] -->|stdio MCP| McpServer[moryn mcp]
    Claude[Claude] -->|stdio MCP| McpServer
    Gemini[Gemini] -->|stdio MCP| McpServer
    Cursor[Cursor] -->|stdio MCP| McpServer
    Shell[Shell/脚本] -->|CLI| Cli[moryn CLI]
    McpServer --> Engine[core/engine.ts]
    Cli --> Engine
    Engine --> Store[(本地 Git 仓库<br/>Moryn Store)]
    Engine --> Lifecycle[agent-lifecycle]
    Engine --> Autocap[autocapture-policy]
    Engine --> Safety[action-safety]
    Store <-->|push/pull| GitRemote[(可选 Git Remote)]
    Dashboard --> Store
```

简而言之：**Moryn = CLI + MCP stdio + 本地 Git 存储 + 生命周期/捕获/安全策略**。Agent 不直接持有记忆，所有读写都经由 CLI 或 MCP 服务落到用户拥有的本地仓库；Dashboard 提供本地可观测性用于人工审查（v0.1.1 新增 `moryn dashboard` 命令）。

## 6. 安装与典型用法

最简启动路径（适配 Codex 等宿主） ([README.md:35-44]())：

```bash
moryn setup --host codex --project . --apply
moryn install --host codex --project . --apply
moryn context pack --project . --agent codex
moryn capture session --project . --agent codex --summary "Finished the task and left handoff notes."
```

需要诊断记忆质量或生命周期时，使用只读 doctor / lifecycle 报告；需要按时间线追溯时使用 `moryn timeline --record-id ... --before 5 --after 5`（[README.md:70-105]()）。

## See Also

- [Contracts](docs/contracts.md) — 操作契约、选择源路径、动作模板与结构化恢复元数据
- [Agent Workflow](docs/agent-workflow.md) — Agent 端到端工作流
- [Agent Install Prompt](docs/agent-install-prompt.md) — 可复制给 Agent 的安装提示
- [Dashboard](docs/dashboard.md) — `moryn dashboard` 本地可观测面板
- [Design Spec](docs/moryn-design.md) — 详细设计规范

---

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

## Agent 生命周期、上下文包与工作流

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [内存模型、安全分级与诊断工具](#page-3)

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

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

- [src/core/agent-lifecycle.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/agent-lifecycle.ts)
- [src/core/agent-identity.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/agent-identity.ts)
- [src/core/action-safety.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/action-safety.ts)
- [src/core/autocapture-policy.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/autocapture-policy.ts)
- [package.json](https://github.com/Richardyu114/Moryn/blob/main/package.json)
- [README.md](https://github.com/Richardyu114/Moryn/blob/main/README.md)
</details>

# Agent 生命周期、上下文包与工作流

## 概述

Moryn 的 Agent 生命周期层为多 Agent 协作提供了一套可审计、可回放的"会话剧本"。它以本地 store 为中心，把一次完整的代理任务拆成 `agent_enter` → `agent_start` → `agent_status` → `agent_finish` 几个阶段，并附带上下文包（context pack）、选择源路径（selection sources）以及安全护栏（guardrails），让 Codex、Claude、Cursor、Gemini、shell agent 等不同宿主能够遵循同一份语义完成启动、续接、状态发布和交接。所有写操作都要求 `safe_to_run: false` 直至显式确认，确保用户始终拥有最终决定权 资料来源：[src/core/agent-lifecycle.ts:1-80]()。

`@richardyu114/moryn` 包以 ESM 模块形式发布，主入口为 `dist/index.js`，CLI 二进制名为 `moryn`，对应实现位于 `src/core/agent-lifecycle.ts` 中的 `agentGuide`、`agentStart`、`agentStatus`、`agentFinish` 等函数 资料来源：[package.json:1-50]()。当前公开版本为 v0.1.1，已上线 `moryn dashboard` 等本地观测能力 资料来源：[README.md:1-40]()。

## 生命周期阶段与上下文包

生命周期由若干步骤（step）组成，每个步骤都返回一份"动作模板 + 上下文包"。`agentGuide` 默认推荐的入口是 `agent_enter`，并在响应中给出 `startup`、`lifecycle`、`lifecycle_by_step`、`rules`、`guardrails` 五个字段，方便调用方按需选择 资料来源：[src/core/agent-lifecycle.ts:120-200]()。常见步骤及触发条件如下：

| 步骤 | 工具 | `safe_to_run` | 触发场景 | 必需字段 |
| --- | --- | --- | --- | --- |
| `start_or_resume` | `agent_start` | true | Agent turn 开始、store/project/sync 上下文不确定 | `current_task`, `sync_remote` |
| `publish_status` | `agent_status` | false | 长任务中途、下次中断前、跨 Agent 协调 | `status` |
| `finish_handoff` | `agent_finish` | false | 任务结束、交接前 | `summary` |
| `refresh_context` | `agent_start` | true | 用户要求刷新 / 收到 refresh cursor | `refresh_since`（可选） |

`agentStart` 会先校验 `agent` 身份字段，再解析项目上下文（`resolveLifecycleProjectContext`），然后根据 `sync_mode` 决定是否自动 `pull`，并在 `sync.before / pull / pull_error / after` 中记录 Git 同步结果 资料来源：[src/core/agent-lifecycle.ts:60-120]()。所有阶段都共用 `lifecycleActionArguments` 生成 CLI/MCP 调用的入参，从而保证在 `startup` 与 `next.actions_by_id` 中取出的命令行模板是等价的。

会话有效期通过常量 `ACTIVE_SESSION_TTL_MINUTES = 120` 控制，超过两小时的活动会话会被视为过期，需要重新 `start_or_resume` 资料来源：[src/core/agent-lifecycle.ts:1-40]()。

```mermaid
flowchart LR
  A[agent_enter / agentGuide] --> B[agent_start\nstart_or_resume]
  B --> C{长任务?}
  C -- 是 --> D[agent_status\npublish_status]
  C -- 否 --> E[agent_finish\nfinish_handoff]
  D --> E
  E --> F[下一个 Agent\nstart_next_session]
  F --> G[agent_start\nrefresh_context]
```

## Agent 身份识别与选择源

Moryn 通过正则白名单识别常见 Agent：`codex`、`claude`、`kimi`、`gemini` 被归为"已知"（confidence: `known`），`agent`、`cli`、`mcp`、`moryn` 等本地通用客户端被归为"通用"（`generic`），其余原始字符串保留为 `unknown` 资料来源：[src/core/agent-identity.ts:1-60]()。`normalizeAgentIdentity` 同时把原始 `raw_client` 一并返回，方便审计。

`agent_enter` 在 `mode: "discover_projects"` 时返回 `projects.projects_by_id.<project_id>` 等选择源路径，调用方必须先从中挑选一个 `project_id` 再调用 `agent_start`，否则会触发 `choose_discovered_project_id` 步骤并标记 `safe_to_run: false` 资料来源：[src/core/agent-lifecycle.ts:200-320]()。`DISCOVER_PROJECT_SELECTION_SOURCES` 与 `GUIDE_SELECTION_SOURCES` 把这些路径集中导出，确保 CLI、MCP 和 dashboard 共用一套寻址规则。

## 安全护栏与自动捕获策略

护栏（guardrail）以"必须避免的行为 → 风险 → 替代动作"的形式呈现：

- `choose_discovered_project`：在项目上下文不明时，禁止猜测 `project_id`，必须走 `agent_enter` discovery 流程 资料来源：[src/core/agent-lifecycle.ts:320-420]()。
- `use_returned_actions_verbatim`：禁止凭记忆重建命令，必须直接消费返回的 `command` 字符串或 `arguments`，仅填充 `required_fields` 列举的占位符 资料来源：[src/core/agent-lifecycle.ts:320-420]()。
- `publish_status_and_finish_handoff`：要求在长中断前调用 `agent_status`，在任务结束时调用 `agent_finish` 留下 summary 资料来源：[src/core/agent-lifecycle.ts:320-420]()。
- `pass_sync_remote_for_cross_device_handoff`：跨设备交接时必须显式传入 `sync_remote` 资料来源：[src/core/agent-lifecycle.ts:320-420]()。

`action-safety.ts` 把这些约束翻译成机器可读的运行手册（runbook），步骤包含 `collect_required_inputs`、`ask_user_confirmation`、`call_mcp`、`do_not_run` 四种，并暴露 `missing_required_fields`、`required_inputs`、`choice_options` 等选择源供前端回显 资料来源：[src/core/action-safety.ts:1-80]()。

`autocapture-policy.ts` 定义了自动捕获 handoff 的策略：当内容命中 `review_risk_marker` 等高风险标记时，决策为 `decision: "capture"`、`route: "review"`、`target_state: "candidate"`、并在 dashboard 的 `capture_inbox` 面板暴露 `user_action_required: true`；低风险 handoff 则走 `route: "auto_capture"`，但仍以 `candidate` 状态进入存储，不会自动晋升为 `canonical` 资料来源：[src/core/autocapture-policy.ts:1-80]()。

## 失败模式与排错

常见失败点与对应错误契约均集中定义：

- 身份字段缺失或类型错误会抛 `AgentIdentityError`，并附带 `recovery_hint` 指明 `operations_by_id.agent_start` 中应补齐的字段 资料来源：[src/core/agent-lifecycle.ts:120-200]()。
- `status` / `summary` 为空字符串会抛 `AgentLifecycleTextArgumentError`，错误对象内嵌 `retry_with.value_placeholder: "<status>"` 等占位符，便于客户端提示用户重新输入 资料来源：[src/core/agent-lifecycle.ts:420-520]()。
- Git 同步冲突时，`assertSyncNotConflicted` 会写入 `sync.before.conflict` 字段，调用方应先解决冲突再继续 `agent_start` 资料来源：[src/core/agent-lifecycle.ts:60-120]()。
- 自动捕获命中敏感标记时，记录会被写入 `quarantined` 状态，在 `boot`、`recall`、`timeline` 等读取路径中被默认隐藏，需要显式 `--include-private` 才会出现 资料来源：[README.md:40-120]()。

## 参见

- [Agent Install Prompt](docs/agent-install-prompt.md)
- [Agent Workflow](docs/agent-workflow.md)
- [Contracts](docs/contracts.md)
- [Dashboard](docs/dashboard.md)
- [Design Spec](docs/moryn-design.md)

---

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

## 内存模型、安全分级与诊断工具

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [Agent 生命周期、上下文包与工作流](#page-2), [Dashboard、Git 同步与 MCP 可观测性](#page-4)

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

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

- [README.md](https://github.com/Richardyu114/Moryn/blob/main/README.md)
- [package.json](https://github.com/Richardyu114/Moryn/blob/main/package.json)
- [src/core/agent-lifecycle.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/agent-lifecycle.ts)
- [src/core/agent-identity.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/agent-identity.ts)
- [src/core/autocapture-policy.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/autocapture-policy.ts)
- [src/core/action-safety.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/action-safety.ts)
- [src/core/schema.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/schema.ts)
- [src/core/sensitive.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/sensitive.ts)
- [src/core/derived.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/derived.ts)
- [src/core/capture-review.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/capture-review.ts)
- [src/core/capture-policy-report.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/capture-policy-report.ts)
</details>

# 内存模型、安全分级与诊断工具

## 1. 概述

Moryn 的核心是本地优先、用户拥有的上下文存储与交接层。它在多 Agent、多设备的 AI 协作中扮演"记忆总线"的角色：Agent 通过 CLI 或 MCP stdio 服务读取、写入、修订、晋升并交接上下文，而所有记忆的所有权始终属于用户。围绕这一目标，Moryn 在源码层面提供了一套完整的内存状态机、敏感度分级机制、自动捕获策略以及诊断工具链，分别由 `schema.ts`、`sensitive.ts`、`autocapture-policy.ts`、`derived.ts`、`capture-review.ts`、`capture-policy-report.ts` 等模块实现 [README.md:1-40]()。

本主题聚焦于：
- 内存记录的有限状态模型与生命周期转换
- 敏感度标签（`private`、`secret`、`sensitive`）的读写隔离
- 自动捕获策略的路由规则
- 诊断与策略报告工具的输出形态

## 2. 内存状态模型

Moryn 把任意一条上下文记录视为有限状态机中的一个节点，并定义了五种状态 [README.md:1-20]()：

```mermaid
stateDiagram-v2
    [*] --> raw
    raw --> candidate: 自动捕获
    candidate --> canonical: 用户/Agent 确认
    candidate --> archived: 判定为非关键
    candidate --> quarantined: 命中敏感或风险标记
    canonical --> archived: 降级保留
    canonical --> quarantined: 风险升级
    archived --> [*]
    quarantined --> [*]
```

各状态语义如下：

- `raw`：原始素材，默认隐藏，不参与常规召回。
- `candidate`：可能有用但尚未被信任的中间状态。
- `canonical`：默认召回的稳定上下文，是用户视角下的"长期记忆"。
- `archived`：仅作为历史保留，默认隐藏，便于审计与回溯。
- `quarantined`：隔离区，存放含敏感或风险标记的内容，默认隐藏。

转换由 `capture-review.ts` 与 `autocapture-policy.ts` 共同驱动，规则全部以只读策略报告的形式呈现，不会自动改写记录本身 [README.md:1-15]()。

## 3. 安全分级与隔离

Moryn 把 `private`、`secret`、`sensitive` 视为主动记录的标签，但它们在常规操作中被显式排除。被排除的接口包括 `boot`、`recall`、`refresh`、`list-recent`、`timeline`、`memory doctor`、`memory lifecycle`、`capture policy`、`dogfood report` 以及 Dashboard 的常规视图 [README.md:1-25]()。

要访问这些记录，必须显式声明意图：

| 触发方式 | 适用场景 | 资料来源 |
| --- | --- | --- |
| CLI `--include-private` | 人工排查或审计 | [README.md:1-25]() |
| MCP `include_private: true` | Agent 受控检索 | [README.md:1-25]() |
| 高风险 canonical 写入 | 需要用户显式确认 | [README.md:1-25]() |

`src/core/sensitive.ts` 负责标签的归一化与匹配，`src/core/derived.ts` 在派生视图（timeline、dogfood report 等）中对带标签记录做脱敏或剔除，而 `agent-identity.ts` 则确保每次写入都附带 `client`、`session_id`、`model`、`device_id` 等可追溯身份字段 [src/core/agent-identity.ts:1-30]()[src/core/agent-lifecycle.ts:1-50]()。

## 4. 自动捕获与诊断工具

### 4.1 自动捕获策略

`src/core/autocapture-policy.ts` 是路由中枢。它评估传入的捕获请求并返回 `policy_id`、`version`、`decision`、`route`、`target_state`、`review_required`、`user_action_required` 等字段。命中 `review_risk_marker` 的请求会进入 Dashboard 的 `capture_inbox` 表面，等待批量审批；低风险交接则自动落入 `candidate` 状态，附带 `auto-captured` 标签 [src/core/autocapture-policy.ts:1-60]()。

### 4.2 诊断与策略报告

诊断链路由 `memory doctor`、`memory lifecycle` 与只读的 `capture_policy` 报告组成。后者解释自动捕获、审核、归档的路由逻辑，但**不会修改存储**——这是 Moryn 区别于"黑盒记忆 SDK"的关键约束 [README.md:1-25]()。`action-safety.ts` 为每条返回的命令计算 `ready_to_run`、`blocked_by`、`runbook`，并在写操作前给出 `requires_user_confirmation` 标记，保证高风险动作只能由显式意图触发 [src/core/action-safety.ts:1-80]()。

### 4.3 常见失败模式

- **在未知项目上下文下写入**：会触发 `AgentIdentityError`，推荐先调用 `agent_enter` 完成发现并选择 `project_id` [src/core/agent-lifecycle.ts:1-50]()。
- **凭记忆拼装命令**：可能改写字段名、丢失占位符，应直接使用响应中 `next.actions_by_id` 返回的命令串 [src/core/agent-lifecycle.ts:1-50]()。
- **跨设备交接未传 `sync_remote`**：状态与摘要可能仅停留在本机 [src/core/agent-lifecycle.ts:1-50]()。

## 5. 开发与发布检查

`package.json` 定义了构建、类型检查、单测与发布前自检脚本。建议在发布前运行 `npm run release:check`，必要时设置 `MORYN_PRIVATE_GIT_REMOTE` 指向专用测试仓库，以完成真实远程写入验证 [package.json:1-50]()[README.md:1-50]()。

## See Also

- Agent 安装与协作流程：[Agent Workflow](docs/agent-workflow.md)
- 命令与数据结构契约：[Contracts](docs/contracts.md)
- Dashboard 使用说明：[Dashboard](docs/dashboard.md)
- 总体设计规范：[Design Spec](docs/moryn-design.md)

---

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

## Dashboard、Git 同步与 MCP 可观测性

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [Agent 生命周期、上下文包与工作流](#page-2), [内存模型、安全分级与诊断工具](#page-3)

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

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

- [src/observability/dashboard.ts](https://github.com/Richardyu114/Moryn/blob/main/src/observability/dashboard.ts)
- [src/observability/dashboard-maintenance.ts](https://github.com/Richardyu114/Moryn/blob/main/src/observability/dashboard-maintenance.ts)
- [src/mcp/server.ts](https://github.com/Richardyu114/Moryn/blob/main/src/mcp/server.ts)
- [src/sync/git.ts](https://github.com/Richardyu114/Moryn/blob/main/src/sync/git.ts)
- [src/core/agent-lifecycle.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/agent-lifecycle.ts)
- [src/core/autocapture-policy.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/autocapture-policy.ts)
- [src/core/action-safety.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/action-safety.ts)
- [README.md](https://github.com/Richardyu114/Moryn/blob/main/README.md)
- [package.json](https://github.com/Richardyu114/Moryn/blob/main/package.json)
</details>

# Dashboard、Git 同步与 MCP 可观测性

## 概述

Moryn 是一个本地优先、用户拥有、可审计的上下文存储与交接层（[README.md:1-10]()）。v0.1.1 重点新增了 `moryn dashboard` 本地可观测性仪表板，使代理在工作中能够直接检查 Moryn 存储状态。可观测性主要由三块组成：本地 Dashboard 视图、Git 同步状态结构化探针，以及通过 stdio MCP 服务器暴露的只读工具。本页围绕这三块说明其作用面、安全边界与典型失败模式。

## Dashboard 本地仪表板

`moryn dashboard` 是面向用户与代理的本地检查入口。其核心只读视图如下表所示：

| 视图 | 对应命令 | 主要用途 |
| --- | --- | --- |
| Capture Inbox | `moryn capture policy --project .` | 审查需要用户决策的自动捕获 handoff |
| Memory Doctor | `moryn memory doctor --project .` | 报告候选积压、可提升记录、烟雾测试噪声 |
| Memory Lifecycle | `moryn memory lifecycle --project .` | 分类活跃记录为保留/陈旧/归档候选 |
| Timeline | `moryn timeline --record-id rec_...` | 按记录/事件/查询锚定的时序邻接视图 |

资料来源：[README.md]()。所有这些视图在默认情况下都隐藏 `private`、`secret`、`sensitive` 标签的记录，调用方必须显式传入 `--include-private` 才可读取（[README.md:41-47]()）。

### 自动捕获策略与仪表板路由

自动捕获策略决定每条 handoff 走哪条仪表板路径，其状态机为：

```mermaid
stateDiagram-v2
    [*] --> raw
    raw --> candidate: low_risk_handoff_auto_capture
    raw --> review: needs_user_decision
    raw --> archive: smoke_test_marker / duplicate_text
    candidate --> canonical: 用户确认
    review --> capture_inbox: user_action_required
    archive --> archived
```

`raw`、`candidate`、`archived`、`quarantined` 四种状态默认在仪表板中隐藏（[README.md:35-40]()）。`capture_inbox` 是仅对需要用户决策的自动捕获 handoff 起作用的人工审查路径；低风险 handoff 仍为本地自动证据，不会自动晋升为 canonical（[README.md:37-39]()）。策略规则定义在 `src/core/autocapture-policy.ts` 的 `DEFAULT_AUTOCAPTURE_POLICY.rules` 中，包括 `smoke_test_marker`、`duplicate_text` 等归档规则（[src/core/autocapture-policy.ts:17-31]()）。

## Git 同步可观测性

Moryn 的 Git 同步由本地存储驱动，远程仓库由用户决定。在 `agentStart` 中同步状态被显式探测：

- `assertSyncNotConflicted(input.storePath)` 在拉取前先行调用以检测冲突（[src/core/agent-lifecycle.ts:5-25]()）。
- `shouldPull` 默认为 `true`，但当 `projectInfo.sync_mode === "manual"` 时跳过拉取（[src/core/agent-lifecycle.ts:5-30]()）。
- 拉取失败会结构化捕获为 `pull_error` 与 `pull_error_details`（类型为 `MorynErrorEnvelope["error"]`），便于上层重试与上报（[src/core/agent-lifecycle.ts:5-35]()）。
- 发布验证脚本通过 `MORYN_PRIVATE_GIT_REMOTE` 写入一次性测试事件（[README.md:67-72]()）。

跨设备交接必须显式传 `sync_remote`；护栏规则 `pass_sync_remote_for_cross_device_handoff` 明确指出缺失该参数时状态与摘要将停留在本机（[src/core/agent-lifecycle.ts:16-20]()）。

## MCP stdio 可观测性

Moryn 通过真实 stdio MCP 服务器暴露工具，依赖 `@modelcontextprotocol/sdk ^1.29.0`（[package.json:11-15]()）。下列 MCP 工具与 CLI 命令一一对应，且全部保持只读：

| MCP 工具 | 对应 CLI | 安全性 |
| --- | --- | --- |
| `health_check` | 隐式 dashboard 状态 | 建议动作保持只读 |
| `recall_eval` | `moryn eval recall` | 不修改记录，不新增索引 |
| `capture_policy` | `moryn capture policy` | 不批准/拒绝/提升/归档 |
| `memory_doctor` | `moryn memory doctor` | 建议动作 `safe_to_run: false` |
| `memory_lifecycle` | `moryn memory lifecycle` | 建议归档动作 `safe_to_run: false` |

资料来源：[README.md]()。`ActionSafety` 中定义的 `safe_to_auto_run`、`requires_user_confirmation`、`requires_authored_input` 字段（[src/core/action-safety.ts:1-12]()）保证了这些建议在用户确认前不会被自动执行；`ActionExecution.runbook` 同时枚举 `collect_required_inputs`、`ask_user_confirmation`、`call_mcp`、`do_not_run` 四类步骤，使代理在阻塞时具有可追溯的恢复路径（[src/core/action-safety.ts:14-32]()）。

## 常见失败模式

- **误以为可见即全部**：仪表板默认隐藏 `private`/`secret`/`sensitive` 记录，若代理据此下结论会遗漏敏感上下文（[README.md:41-47]()）。
- **跨设备误以为已同步**：未传 `sync_remote` 时 handoff 仅落本机，状态摘要不会到达远端（[src/core/agent-lifecycle.ts:16-20]()）。
- **把只读工具当作写入工具**：`recall_eval`、`capture_policy`、`memory_doctor`、`memory_lifecycle` 均不修改存储；调用方若把它们当作执行入口会得到非预期结果（[README.md]()）。
- **跳过显式确认直接晋升 canonical**：高风险 canonical 写入要求用户显式确认，自动跳过将违反 `requires_user_confirmation` 边界（[src/core/action-safety.ts:1-12]()）。

## 参见

- [Agent Workflow](https://github.com/Richardyu114/Moryn/blob/main/docs/agent-workflow.md)
- [Contracts](https://github.com/Richardyu114/Moryn/blob/main/docs/contracts.md)
- [Agent Install Prompt](https://github.com/Richardyu114/Moryn/blob/main/docs/agent-install-prompt.md)

---

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

---

## Doramagic 踩坑日志

项目：Richardyu114/Moryn

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<!-- canonical_name: Richardyu114/Moryn; human_manual_source: deepwiki_human_wiki -->