# 计划评审与审计追踪

召回项目约束，将提议的计划与证据进行比对，跟踪生命周期结果（已规划、已提交、已合并、已发布、已验证），并保存带有来源溯源的已批准结果。

- Canonical: https://docs.xmemo.dev/zh/docs/guides/plan-review-and-audit
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 175b0b54be778ea414d888fa51982bb437637db88fc7fe769ca86ce36f314e63
- Edition-Digest: 979454a22dde51b7f03914b62d43eda8058512237817141ddbab96f19e5c3a85
- Source-Revision: sha256:fe7c573aca1054f57d1a9a3473cb5469fb99b6d0edc9e97966d5f99565482dbd

## 用户目标与工作流边界

这一实用工作流指导开发者和评审 agent 依据代码仓库的经验性证据，对软件提案、技术规范和架构计划进行审计。评审人员将计划中的断言与存储的项目约束进行对比，跟踪跨离散生命周期阶段（planned、submitted、merged、released、verified）的变更，并持久化保存带有不可变来源归属的已批准共识决定。

## 可用性与前提条件

审计与计划评审能力跨 MCP 客户端配置文件和独立 Skill CLI 提供：

- MCP cursor-plugin 与 ordinary-full 配置文件：提供全面的评审能力：get_project_context（只读项目包）、recall_context、search_knowledge、update_project_decision（状态转换决定：resolve、supersede、reopen）、update_project_todo（状态转换工作项：accept、assign、block、unblock、complete、cancel）以及 query_audit（审计事件和整合记录）。
- MCP claude-plugin 配置文件：包括 get_project_context、recall_context、create_pending_decision、resolve_decision、record_event、remember、recall 和 todo。
- MCP generic-public、chatgpt-public 和 public-only 配置文件：支持带有 focus="blockers" 或 focus="status" 的 get_project_summary(project_id, focus) 以获取快速摘要，以及用于统计的 memory_overview。
- 独立 Skill（Claude Code、Codex、OpenClaw）：来自服务版 1.1.35 help.mjs 的逐字命令：recall-context（第 84-87 行）、search（第 80-83 行）、remember（第 72-75 行）、update（第 44-47 行）、todo-add/list/done（第 112-123 行）以及 activity/stats（第 64-71 行）。
- 前提条件：读取作用域（memory:read）用于查询项目上下文和审计历史；写入作用域（memory:write）用于记录决定和更新工作项。

## 一个完整任务：审计服务迁移计划

在这个合成审计演练中，agent 审查项目 proj_security_core 的认证升级提案，对照代码仓库约束验证断言，转换工作项状态，并存储已批准的结果。

## 召回项目约束与审计历史

使用 recall-context 或 get_project_context 检索已确立的项目准则并检查先前决定的来源：

```bash
node scripts/xmemo-skill.mjs recall-context --query "token revocation policy session lifetime proj_security_core" --max_items 6 --max_tokens 2500
```

## 转换工作项状态并记录决定

将评审 TODO 标记为已完成，并保存带有来源的权威决议：

```bash
node scripts/xmemo-skill.mjs todo-done --id todo_rev_401
node scripts/xmemo-skill.mjs remember --content "Approved plan auth_migration_v3: enforced 24h token revocation, strict mutual TLS, and zero unauthenticated fallback. Verified by reviewer audit." --path "plans/auth_migration_v3"
```

## 可观察结果

结构化的计划审计会创建反映离散生命周期里程碑的不可变、可验证的追踪记录：

- 五个截然不同的里程碑状态：计划和工作项通过明确的阶段推进：planned（起草的规范）-> submitted（请求正式评审）-> merged（实现已合并）-> released（打包并已部署）-> verified（部署后验证通过）。切勿将 planned 与 released 或 verified 混淆。
- 确定性审计追踪：query_audit 返回包含事件时间戳、操作 agent_id、目标记忆/决定 ID 以及前后状态差异的结构化记录。
- 来源保留：使用 recall 或 recall_context 查询记忆时，结果会公开不可变的来源元数据，明确标识授权会话与时间戳。

## Agent 可以访问的内容

执行计划评审和审计的 agent 与结构化、有边界的表示进行交互：

- 仅追加审计日志：审计事件日志为仅追加（append-only）。Agent 无法覆盖、篡改或删除历史决定审计记录。
- 版本 DAG 与替代：更新现有决定或记忆会创建一个链接到其前置版本的新版本；之前的状态仍可作为被替代的版本进行检索（cursor-plugin / ordinary-full 中的 list_memory_versions）。
- 基于证据的上下文：Recall 工具返回从项目记忆中提取的事实证据，防止 agent 将未经证实的模型推论误认为已记录的项目决定。

## 共享与存储边界

审计记录和决定受严格的多租户与项目分区管辖：

- 项目作用域界定：绑定到 project:proj_security_core 的决定和工作项与无关的个人项目或外部团队空间保持隔离。
- 便签排除：临时的开发者便签（scratchpad）、本地调试日志和瞬态想法切勿写入持久决定记录中。
- 归属不可变性：服务器使用经过身份验证的调用者 owner_identity 和 source_identity 对每个决定进行标记；客户端无法伪造或冒充其他 agent。

## 故障恢复

使用标准解决途径管理审计差异和评审冲突：

- 未经证实的计划断言或矛盾：如果提议的计划与现有的架构决定相冲突，请不要解决该决定。使用 action="supersede" 或 action="reopen" 转换该决定，并附带详细描述差异的 resolution_note。
- 缺少工作项或决定 ID：当引用的 todo_id 或 decision_id 无法找到时，使用 todo-list（Skill）或 get_project_context(project_id="proj_security_core") 查询活动条目以定位规范 ID。
- 作用域权限被拒绝：如果 agent 缺少目标项目的写入权限，update_project_decision 将返回 HTTP 403 Forbidden。请向项目管理员上报以分配角色。

## 相关参考

有关相关安全概念、来源详细信息以及工作项管理，请参阅以下指南：

- 来源与归属：/docs/concepts/provenance-attribution 了解调用者归属规范。
- TODO 工作项参考：/docs/tools/todos 了解项目任务跟踪。
- 分类账交易参考：/docs/tools/ledger 了解财务与资源审计。
- 恢复与 agent 移交：/docs/guides/resume-and-handoff 了解会话检查点工作流。
- 项目指南：/docs/concepts/projects 了解项目工作区组织。

## ChatGPT 用户

让 ChatGPT 持久访问你的 XMemo 偏好、项目事实、决策和 TODO，同时不把 bearer token 粘贴到聊天里。

通过 ChatGPT/OpenAI app 的 OAuth 流程连接托管 XMemo MCP server，然后为你的 XMemo 账户批准 memory:read 与 memory:write 授权。

保存一条合成偏好或项目笔记，开启新聊天，再让 ChatGPT 在继续工作前通过 XMemo 召回它。

如果 OAuth 失败或工具未出现，先在宿主应用里退出该 MCP server，重新连接 XMemo server URL 并重试，再考虑创建 direct token。

## Copilot / Codex 开发者

在 IDE 与 CLI agent 之间携带仓库决策、编码规范、bug 修复说明和任务历史。

在可用时对 VS Code / GitHub Copilot 和 Gemini CLI 使用 OAuth。对于 Copilot CLI、Codex、Cursor 或其他直连 MCP 客户端，请在本地环境或密钥存储中保留 XMEMO_KEY，并设置稳定的 XMEMO_AGENT_INSTANCE_ID。

记录一条代码库决策或 bug 修复，然后让下一个 IDE 或 CLI agent 在编辑前召回相关 XMemo 上下文。

如果召回为空，检查所选 MCP 配置路径、direct client 的 XMEMO_KEY 环境变量，以及宿主应用中是否存在过期 OAuth 凭据。

## 团队 / 企业 pilot owner

用账户控制、来源归因、导出/删除流程和 reviewer-safe 设置证据来评估共享记忆。

创建或进入受保护的 XMemo workspace，邀请已批准用户，然后根据 readiness badges 通过 OAuth 或 scoped direct credential 连接各客户端。

让一名 pilot 成员保存一条合成团队记忆，在 XMemo 中确认来源归因，然后审阅删除/导出和支持路径。

如果成员无法连接，先检查角色权限、OAuth 批准、客户端 readiness 状态和支持指引，再签发新 token。

## 自主 agent operator

让 headless 或定时 agent 记录进度、取回历史决策，并保持稳定的非秘密实例身份。

获取 /api/v1/mcp/config/autonomous-agent。当 runner 支持 OAuth + 自定义 headers 时优先使用 auth_modes.oauth；只有完全 headless 的 runner 才使用 auth_modes.xmemo_key，并从密钥库读取 XMEMO_KEY。

运行一个会向 XMemo 写入进度的合成任务，重启 runner，并确认它使用同一个 XMEMO_AGENT_INSTANCE_ID 召回该进度。

如果归因变化或召回分散到多个实例，请把 XMEMO_AGENT_INSTANCE_ID 持久化到 git 之外，并确认 runner 不会每次启动都重新生成它。