开始使用

在 5 分钟内完成 Datarim 配置

使用 AI 智能体?

给它仓库 URL,让它安装 Datarim;它会遵循 INSTALL.md。智能体的第一步:运行 ./install.sh --project <path>,不带任何答案标志,且在该次运行前不要向你询问任何问题。没有终端时,安装程序会以 STOP 停止,打印六个问题及其默认值和一个一次性答案令牌,并告诉智能体逐字转述这些问题,不推荐任何答案。智能体用你的答案和该令牌重新运行。

# 代码仓库
https://github.com/Arcanada-one/datarim

# 指南原文(网页摘要抓取会丢失大部分内容)
https://raw.githubusercontent.com/Arcanada-one/datarim/v4.12.3/INSTALL.md
本页遵循标准安装指南,即 GitHub 上的 INSTALL.md。如果两者有出入,以 INSTALL.md 为准。

1 前置条件

  • Python 3.10 或更新版本,以及 git。
  • 至少安装并登录一个智能体客户端:Claude Code(claude)、Codex CLI(codex)、Cursor CLI(cursor-agent 或 agent)、Google Antigravity(agy)或 MiniMax Code(mcode)。Datarim 不创建客户端账户,也不读取模型提供商的密钥;每个客户端自行登录。
  • 项目目录。推荐使用 git 仓库:这样安装程序才能通过 .git/info/exclude 隐藏其文件。
  • 仅用于 Jev 路由建议:一个 Jev API 密钥,由 Jev API 提供商 TypeSafe(api.typesafe.ai)签发。你需要每台计算机一个密钥,由该机器上的所有客户端共享。没有密钥时,Jev 仍会运行其本地安全底线;只是缺少路由建议。

2 获取源码

git clone https://github.com/Arcanada-one/datarim.git ~/src/datarim
cd ~/src/datarim
git checkout "$(git describe --tags --abbrev=0 --match 'v*')"   # 最新发布标签

保留此检出:update.sh 和 --uninstall 之后会从这里运行,因此请把它放在持久位置,例如 ~/src/datarim,绝不要放在 /tmp,也绝不要放在项目内部。停留在 main 分支也受支持。安装的提交记录在 <project>/.datarim-runtime/installation.json(source_sha)中。要将项目固定到某个发布版本,请在安装或更新前检出该标签(git checkout vX.Y.Z)。Host Jev 拒绝从有未提交更改的检出安装。

共享仓库与报告交付

当队友不使用 Datarim 时,在已应答的安装命令中加上 --team-neutral。安装和更新不会改动根目录的指令文件。如果仍残留旧版受管理的根块,更新会停止,直到手动移除该块。只有 datarim/AGENTS.md、datarim/config.yaml 和 datarim/local/ 对 Git 可见;任务状态保持私有。

delivery:
  reports: reports/datarim/{task_id}

将以下内容放入 datarim/config.yaml,即可在经审核的项目相对路径下发布 QA 与合规报告。报告副本会与工作副本进行校验。若缺少该键,私有报告仍可供 Datarim 用户使用,工作流会报告一条可见性提示。

阅读团队中立指南

你的回复语言、你的项目文档语言

两者默认均为英语。可一次性设置个人偏好,或选择共享与私有项目默认值。项目文档策略优先于个人文档默认值;你的个人回复语言优先于共享对话默认值。原生受管理/安全规则仍然适用。

python3 .datarim-runtime/skills/human-outcome-reporting/scripts/language.py configure --scope user --replies fr --artifacts en
python3 .datarim-runtime/skills/human-outcome-reporting/scripts/language.py resolve --project "$PWD"

在项目安装后运行。若需独立报告,请使用已安装技能目录中的辅助脚本,例如 Codex 的 ~/.agents/skills/human-outcome-reporting/scripts/language.py。用户设置位于 $XDG_CONFIG_HOME/datarim/config.yaml,若不存在则回退到 ~/.config/datarim/config.yaml。项目设置使用 datarim/config.yaml 和私有的 datarim/config.local.yaml;普通安装会将 datarim/ 排除在 git 之外;--team-neutral 仅暴露共享配置和本地扩展。

解析时会重新读取偏好设置;无需重新安装。若旧上下文仍然存在,请开启新对话,尤其是在使用 Cursor 会话启动钩子时。安全语言标签无需双语白名单即可接受。固定渲染器标签需要可用的目录;缺少覆盖时使用已披露的英语回退。保留引用的简报、现有正文、代码和机器值。

最近的私有 datarim/config.local.yaml 会选择其自身项目,即使位于祖先框架之下也是如此。格式错误的设置或损坏的私有标记属于错误,而不是成功回退到祖先。使用 configure --scope local --project /absolute/path/to/project 设置私有偏好;请将该文件排除在公开源码之外。

配置语言 · 优先级与限制 · 试一试

不依赖 Datarim 的 Human Outcome Reporting

4.2.3 主分支从新的签名根开始。保留现有的本地分支和编辑;请使用单独的干净源码克隆,而不是合并新旧历史。 迁移指南.

如果你希望在每个项目中都能获得清晰的智能体报告,而又不想安装框架,请选择此方式。便携技能 0.3.3 已包含在 Datarim 4.4.0 中,也可独立使用。从发布页下载独立 ZIP 及其签名校验和,按发布指南所述进行校验,然后解压归档:

human-outcome-reporting.zip · 下载发布资源

解压前,下载 ZIP、其 .sha256 校验和以及 .cosign.bundle。验证校验和、可信工作流签名和 GitHub 证明;三者都必须成功。验证软件包。

python3 install.py install --agents antigravity,claude,codex,cursor,minimax --dry-run
python3 install.py install --agents antigravity,claude,codex,cursor,minimax
python3 install.py check --agents antigravity,claude,codex,cursor,minimax

或者从已检出的发布版本执行:python3 scripts/human_reporting_install.py install --agents antigravity,claude,codex,cursor,minimax。在 macOS 或 Linux 上使用 Python 3.9 或更新版本;可选的报告校验工具需要 Python 3.10 或更新版本。技能目录为 ~/.claude/skills、Codex 的 ~/.agents/skills、~/.cursor/skills、Google Antigravity(agy)的 ~/.gemini/config/skills,以及 MiniMax Code(mcode)的 ~/.minimax/skills。安装器会将技能添加到每个选定的客户端及其原生持久策略:Claude 输出样式、受管理的 Codex AGENTS.md 块、Cursor 会话启动上下文,以及 ~/.gemini/config/hooks.json 中 datarim-human-outcome-reporting 钩子组下的 Antigravity SessionStart 回调。现有的外部规则和钩子会被保留;冲突的已拥有路径会被拒绝。重启客户端并测试新会话。对于 Cursor 和 Antigravity,请开启新对话;恢复现有聊天不会重新运行会话启动钩子。项目特定的 Claude 输出样式可能优先。用户配置适用于此账户;请为另一主机或远程账户单独安装。安装检查只能证明文件和配置,不能证明未来每个回答都会遵守。

0.3.3 版还为受支持的 Codex、Claude Code、Google Antigravity 和 MiniMax Code 客户端注册了同步 SessionStart 回调。它们会在首条进度消息之前读取原生工作目录的当前偏好,包括新启动或恢复之后;偏好变更时无需重新安装。在 Codex 中,使用 /hooks 通过原生信任控制查看新增或变更的钩子定义。安装程序不会授予信任、绕过审批或更改权限设置。现有的外部钩子和安全钩子保持不变。如果钩子不受支持、被禁用或不受信任,已安装文件检查无法建立启动上下文。请检查原生激活情况,然后在新会话中观察首条进度消息、最终回复和产物。

Claude 会在提交提示词之前通过 UserPromptSubmit 刷新偏好,并在工具完成或失败后通过 PostToolUse 和 PostToolUseFailure 刷新偏好。普通进度和工具叙述使用回复语言;可复用笔记使用产物语言。显式的文档语言请求只更改该产物;回复语言请求只更改回复正文。这些同步回调在不改变输出、决策或权限的情况下添加上下文。工具后输入限制为 1 MiB;启动和提示词输入保留 64 KiB 限制。无效或过大的元数据会披露未解析的偏好。工具失败回调不包括权限拒绝、执行前验证失败和取消。上下文传递不保证模型遵循。此安装程序在 Codex 中没有逐轮回调;如果先前的启动上下文仍然存在,请开启新对话。偏好变更无需重新安装;变更钩子安装需要重新进行激活检查。

生成的回调执行当前偏好辅助程序源码,而不是现有的辅助程序字节码缓存。它们保留外部缓存,并且不写入辅助程序字节码。安装程序的 check 验证文件一致性;runtime_behavior、startup_context、per_turn_context 和 post_tool_context 仍为 not_measured。请分别观察实际的首条进度文本、最终回复和已保存文档。

在聊天回复中生成的可复用 Markdown 笔记或文档摘录仍属于产物。其正文和示例使用产物语言;其外部的说明使用回复语言。不会添加未经请求的翻译示例。显式的双语或翻译请求、逐字输入、代码和机器标识符保留其例外,原生权威仍然优先。

对于 Datarim 项目,请安装或更新下方框架;其命令会自动加载相同的报告技能。主机级报告不会在其他项目中激活 Datarim。python3 install.py uninstall --agents antigravity,claude,codex,cursor,minimax 仅移除自有独立产物。

Human Outcome Reporting · /dr-explain

3 先决定

设置涵盖以下六个选择:五个设置和源发布版本。在终端中,安装程序会逐一提示设置(按 Enter 采用默认值),并提醒你选择发布版本。没有终端时(智能体、脚本),全新安装会以 STOP. Nothing was installed. 停止,退出码为 2,且不写入任何内容,包括 --dry-run。它会列出问题及其默认值,告诉智能体逐字转述这些问题且不推荐任何答案,并打印一次性 --answers <token>:有效期为 60 分钟,仅限此项目,成功安装后即失效;每次新的拒绝都会替换它。重新运行需要每个答案(Jev、--client、--permissions)和该令牌。AI 智能体绝不自行选择答案;仅在用户明确要求时才接受默认值。

# 问题 默认值
1 安装 Jev?none / project(仅此项目)/ host(此机器上该用户的所有项目) none
2 你使用哪些客户端:Claude Code、Codex、Cursor、Antigravity、MiniMax Code?每个客户端传入一个 --client(或逗号列表);命令以及在使用 --with-jev 时的钩子仅写入这些客户端。 机器上已安装的客户端
3 jev* 启动器(每次安装都有)是否应不提示权限地启动客户端?用 --permissions ask 或 --permissions full 回答:全新安装时必填,更新时会记住;之后可用 jev permissions 更改。直接启动客户端不受影响。 否(ask)
4 现在创建空任务文件 datarim/tasks.md 与 datarim/backlog.md(--init)? 是
5 是否将每个框架技能暴露给客户端的自动发现(--expose-skills)?这会把它们的描述加入每个会话。 否
6 安装最新发布标签,还是 main? 最新发布标签

嵌套 git 仓库:如果项目包含一些嵌套仓库,且 Datarim 应在其中工作,请为每个仓库添加一个 --context <relative/path>。用 find "$PROJECT" -mindepth 2 -name .git -not -path '*/node_modules/*' 找到它们。

4 安装

先设置一次项目路径(绝对路径),然后仅使用项目路径且不带任何答案标志运行安装程序。在此运行之前,智能体不会向用户询问任何内容。

PROJECT=/absolute/path/to/project
./install.sh --project "$PROJECT"   # 在终端中提问;否则打印问题、每个答案对应的标志以及一次性令牌

没有终端时:向用户询问打印出的问题,等待答案,然后在一小时内用答案给出的标志(见下文)和 --answers 加上打印的令牌重新运行。先在该次重新运行中加上 --dry-run 查看计划。没有有效令牌时传入的答案标志会被列为已忽略。绝不自行选择答案:Jev 的安全底线无需任何密钥即可工作,因此缺少密钥不是回答“no Jev”的理由。

选项 A — 仅 Datarim(默认)

用户回答“no Jev” → 标志 --without-jev,加上 --client 列表和他们选择的 --permissions 答案。

切勿代表用户传递它:缺少密钥不是跳过 Jev 的理由,其安全底线在没有密钥的情况下也能工作。

选项 B — Datarim 配合项目级 Jev

用户回答“Jev for this project” → 标志 --with-jev,加上 --client 列表和他们选择的 --permissions 答案。

Jev 钩子仅在此项目中为你选择的客户端注册(.claude/settings.local.json、.codex/hooks.json、.cursor/hooks.json、.agents/hooks.json),并在 config/credentials/jev/api-key 创建一个空密钥文件(模式 0600)。不要在已安装 host Jev 的机器上使用此选项:两组钩子都会运行。请改用选项 C。

选项 C — 主机级 Jev,以及此项目中的 Datarim

用户回答“Jev for the whole machine” → 标志 --with-jev --host-jev,加上 --client 列表和 --permissions 答案。仅在这种情况下,先安装 host Jev:

# 仅当用户选择主机级 Jev 时
python3 scripts/jev_host_install.py --client claude --client codex --client cursor \
  --datarim-project "$PROJECT" --dry-run
python3 scripts/jev_host_install.py --client claude --client codex --client cursor \
  --datarim-project "$PROJECT"

宿主 Jev 按用户安装一次,并应用于该用户打开的每个目录。它会写入 ~/.config/jev/、~/.local/share/jev/、~/.local/state/jev/,启动器 ~/.local/bin/{jev,jevclaude,jevcodex,jevcursor}(该目录必须在 PATH 中),并将其钩子合并到每个所选客户端的用户配置中,同时保留所有现有钩子。--datarim-project 替换宿主的 Datarim 项目列表:之后添加项目时,需再次传入所有项目。密钥文件为 ~/.config/jev/credentials/api-key。

选项 D — Jev 不带 Datarim

python3 scripts/jev_host_install.py --client claude --client codex --client cursor --dry-run
python3 scripts/jev_host_install.py --client claude --client codex --client cursor

同一个宿主安装器,但不带 --datarim-project,也不进行项目安装。详情:单独使用 Jev。

其他安装选项

--client <name> claude、codex、cursor、antigravity(agy)、minimax(mcode)或 all;可重复传入或给出逗号分隔列表。只有这些客户端会获得命令文件以及(配合 --with-jev 时)钩子。全新安装时必填;更新时保留。更新时遗漏的客户端会失去其命令文件和 Jev 钩子。
--claude-import / --no-claude-import 自 4.1 起已弃用:接受但会提示且无效果。Claude Code 原生读取 AGENTS.md;不会创建指令符号链接。
--permissions ask|full 权限模式答案(问题 3)。全新安装时必填,更新时会被记住。它设置与 jev permissions 相同的开关,作用于项目;若使用宿主 Jev,则作用于宿主。
--answers <token> 拒绝时打印的一次性令牌。在没有终端的新安装中,需要它与答案一起使用;有效期为 60 分钟,仅限本项目,成功安装后即失效。每次新的拒绝都会替换它。更新不需要它。
--init 若缺失,则创建 datarim/tasks.md 和 datarim/backlog.md。现有文件会保留。
--expose-skills 还会将每个框架技能写入 .agents/skills/、.claude/skills/、.cursor/skills/。其描述会加载到每个会话中。
--context <relative/path> 允许现有的嵌套 git 仓库使用此安装。按仓库重复传入;再次给出时会替换列表;--no-context 会清除它。
--without-jev, --no-host-jev --without-jev 是全新安装所要求的“不使用 Jev”答案。更新时,它们会关闭已记录的 --with-jev 或 --host-jev;随后 --without-jev 会撤回项目的 Jev 钩子和 jev-config.json;密钥文件保留。
--dry-run 以 JSON 打印计划;不写入任何内容。在没有终端的新安装中,它会像安装本身一样拒绝,直到获得答案和令牌。

仅当用户选择“默认值”时:--without-jev、--client 配合机器上已安装的客户端、--init 和 --permissions ask。

脚本化安装(CI)

没有跳过答案令牌的开关。使用固定、已审核答案的流水线需要两步:第一次运行会拒绝,并在其重运行行上打印令牌;第二次使用相同答案传入该令牌。将 <flags> 替换为已审核的答案标志,两次运行中保持一致:

out="$(./install.sh --project "$PROJECT" <flags> 2>&1)"
token="$(printf '%s\n' "$out" | sed -n 's/.*--answers \([0-9a-f][0-9a-f]*\) .*/\1/p' | tail -n 1)"
[ -n "$token" ] || { printf '%s\n' "$out" >&2; exit 1; }
./install.sh --project "$PROJECT" --answers "$token" <flags>

AI 智能体替人安装 Datarim 时不这样做:它转达首次运行打印的问题,并使用此人的答案。

安装后的报告

每次安装或更新后,安装程序会在围栏代码块内打印其报告行,开头为“将下面的块原样复制到你对用户的回复中(你可以在其后添加自己的文字):”。智能体将整个块原样复制到其回复中,不得改写;其自己的文字可以跟在块后。这些行是:

  • 权限模式及其存储文件:状态目录中的 FULL_PERMISSIONS(存在 = full,不存在 = ask;用 jev permissions full|ask 更改);
  • 使用 Jev 时,密钥文件路径,并注明 Jev 安全底线无需密钥即可工作;用编辑器粘贴密钥,切勿使用 echo 或 printf;
  • 切勿放入 .zshrc/.bashrc:JEV_* 或 DATARIM_* 变量(例如 JEV_PERMISSIONS)或密钥;按 shell 或按启动设置它们;
  • 当项目有 AGENTS.md 时:AGENTS.md is not modified by the installer;
  • 使用 Codex 和 Jev 时,如何接受 Codex 的钩子;使用 Codex 或 Cursor 时,.agents/skills/dr-* / .cursor/skills/dr-* 是为它们打包的 /dr-* 命令,而非额外的框架技能。

安装是项目本地的:框架的固定快照会放入 .datarim-runtime/,/dr-* 命令会放到各客户端查找的位置(Claude Code → .claude/commands/,Codex 和 Antigravity → .agents/skills/,Cursor → .cursor/skills/,MiniMax → .minimax/skills/),并且它写入的所有内容都会通过 .git/info/exclude 从 git status 中隐藏。它不会触碰你的主目录、shell 启动文件、AGENTS.md 或 .gitignore。自 4.1 起,Claude Code 原生读取 AGENTS.md;安装器从不创建 CLAUDE.md。各客户端详情:运行时。

5 Jev 密钥、权限模式和设置

Jev 是可选的。它增加一个确定性的安全底线——一个拒绝破坏性 shell 命令的钩子,无需密钥或网络——并且,使用 API 密钥时,提供模型层级路由建议。该建议只是建议:它不会切换正在运行的模型,也不授予任何权限。

Jev 密钥的放置位置

在编辑器中打开你安装的密钥文件,将密钥粘贴到一行,保存。该文件已存在且权限为 0600;请保持如此。--with-jev 安装会打印确切路径。

安装 密钥文件
项目 Jev(选项 B)<project>/config/credentials/jev/api-key
主机 Jev(选项 C 或 D)~/.config/jev/credentials/api-key
$EDITOR ~/.config/jev/credentials/api-key   # 主机 Jev;项目 Jev:config/credentials/jev/api-key
  • 每台计算机一个密钥,由其所有客户端共享;每台计算机使用不同的密钥。
  • 切勿用 echo 或 printf 将密钥写入文件:该命令会进入你的 shell 历史记录。切勿将密钥放入提交、设置文件或聊天中。
  • export TYPESAFE_API_KEY=... 不起作用:启动器和钩子会移除该变量,只读取文件。
  • 使用主机 Jev 时,项目自己的密钥文件保持为空且不被读取;这是正确的。

权限模式(仅 Jev 启动器)

jev permissions          # 显示当前模式
jev permissions full     # jev* 启动器启动客户端时不显示权限提示
jev permissions ask      # 回到客户端自己的提示(默认)

full 会为通过 jev、jevclaude、jevcodex、jevcursor、jevagy、jevminimax 的启动添加 --dangerously-skip-permissions(Claude Code 和 Antigravity)、--dangerously-bypass-approvals-and-sandbox(Codex)或 --force --approve-mcps(Cursor)或 exec --permission full(MiniMax),除非你传入自己的权限选项。安装器的 --permissions ask|full 答案会设置相同的开关。它按项目(项目安装)或按宿主(宿主 Jev)存储。安全底线在 full 模式下仍会运行。直接启动 claude、codex、cursor-agent 或 agy 不受影响。jev off / jev on 会停止和恢复 API 调用;无论哪种方式,安全底线都会继续运行。

配置与密钥

此处没有任何内容会被提交:项目路径由 .git/info/exclude 隐藏,宿主路径位于你的主目录中。下面的环境变量按 shell 或按启动设置,绝不要放在 .zshrc、.bashrc 或其他启动文件中:例如在那里设置 JEV_PERMISSIONS=full 会为每次 jev* 启动关闭权限提示。持久选择有自己的开关:jev permissions、jev on / jev off 以及设置文件。读取每个设置的代码在 INSTALL.md 中列出。

设置项 位置 是否必需 默认值
Jev API 密钥(项目级 Jev) 文件 <project>/config/credentials/jev/api-key,权限模式 0600 仅用于路由建议 创建时为空
Jev API 密钥(主机级 Jev) 文件 ~/.config/jev/credentials/api-key,权限模式 0600 仅用于路由建议 创建时为空
Jev 设置(项目级) <project>/.datarim-runtime/jev-config.json:端点、超时、重试、路由模式、钩子开关、遥测 否 从 plugins/dr-jev-control/config/jev-control.json 复制
Jev 设置(主机级) ~/.config/jev/config.json,包含 datarim_projects(允许使用 Datarim 的项目) 否 相同的默认值;api.base_url 必须保持为 https://api.typesafe.ai/v1/systemone
开关 jev off / jev on:在 .datarim-runtime/state/jev/ 或 ~/.local/state/jev/ 中创建 DISABLED 文件 否 开启
权限模式 jev permissions full|ask:同一状态目录下的文件 FULL_PERMISSIONS;环境变量 JEV_PERMISSIONS=full|ask 可在单次启动时覆盖该设置 否 ask
为某个 shell 禁用 Jev 建议 环境变量 JEV_DISABLE=1 或 DATARIM_JEV_DISABLE=1(安全底线仍会运行) 否 未设置
按 Jev 层级指定 Codex 模型 环境变量 DATARIM_CODEX_MODEL_HAIKU、_SONNET、_OPUS 否 Codex 账户默认值,层级映射为 effort
按 Jev 层级指定 Antigravity 模型 环境变量 DATARIM_ANTIGRAVITY_MODEL_HAIKU、_SONNET、_OPUS 否 Antigravity 账户默认值,层级映射为 --effort
按 Jev 层级指定 Cursor 模型 环境变量 DATARIM_CURSOR_MODEL_HAIKU、_SONNET、_OPUS 否 Cursor 默认模型
客户端可执行文件 环境变量 CLAUDE_BIN、CODEX_BIN、CURSOR_BIN、ANTIGRAVITY_BIN(或 AGY_BIN) 否 PATH 中的 claude、codex、cursor-agent(或 agent)、agy 或 mcode
按 Jev 层级指定 MiniMax 模型 环境变量 DATARIM_MINIMAX_MODEL_HAIKU、_SONNET、_OPUS 否 MiniMax 账户默认值;设置覆盖时传入 --model
Codex 自动重新信任 环境变量 JEV_NO_AUTO_TRUST=1 会阻止 jevcodex(宿主 Jev)重新向 Jev 自身的钩子授予 Codex 信任 否 未设置
执行主机映射 环境变量 DATARIM_EXEC_HOSTS_MAP,一个 YAML 映射,指明哪台机器可以为某个工作区运行任务 否 $HOME/.claude/local/config/execution-hosts.yml;映射缺失表示跳过该检查

由入口点设置,切勿手动设置:DATARIM_RUNTIME(由 source .datarim-runtime/activate.sh 设置,连同 PATH),以及 DATARIM_ROOT、DATARIM_PROJECT_ROOT、DATARIM_JEV_CONFIG、DATARIM_JEV_HOME、DATARIM_JEV_STATE、TYPESAFE_API_KEY_FILE、JEV_STATE_DIR、JEV_HOST_STATE(由 jev* 和钩子设置)。模型提供商密钥(ANTHROPIC_API_KEY、OPENAI_API_KEY 等)不会被安装器、Datarim 的命令或 Jev 读取;你的客户端保留自己的登录方式。

6 验证

cd "$PROJECT"
git status --short                       # 预期:Datarim 无任何输出
source .datarim-runtime/activate.sh      # 仅当前 shell
jev doctor --agent=claude                # 或 --agent=codex / --agent=cursor / --agent=antigravity / --agent=minimax

预期的 jev doctor 输出(JSON),退出码 0:

  • "scope": "project"(或配合 --host-jev 使用 "host"),"datarim_enabled": true;
  • "findings": [] — 一条 finding 会指明缺失项(例如 claude: executable missing,或 cursor: Jev hook file missing (...)),并使退出码为 1。不带 --agent 时,doctor 会检查全部四个客户端,因此你未使用的客户端也会成为一条 finding;
  • "hook_clients" — 本次安装为其注册了 Jev 钩子的客户端;
  • "config_path" — 正在使用的 Jev 设置文件(.datarim-runtime/jev-config.json,或使用宿主 Jev 时的 ~/.config/jev/config.json);无 Jev 时为 null;
  • "native_agents_live" — 按客户端列出,一旦账本中存有来自该客户端的 hook_delivery 记录,便显示 "state": "live" 及投递次数和最后投递时间;在该客户端运行钩子之前为 not_measured(附带原因)。当注册了多个客户端时,会列出所有已注册客户端,而不仅是 --agent 指定的那个;无投递的客户端显示“尚无投递”;
  • "key_ready": false,直到你添加密钥(true 仅表示文件非空,并不表示密钥有效);
  • "api": "not_measured" — 离线 doctor 不发起网络调用;这既不是通过也不是失败;
  • "source_sha" — 你安装的提交。

添加 Jev 密钥后,jev doctor --api 应以退出码 0 退出,并输出 "api": {"ok": true, "model": "...", ...};缺少密钥会给出 "reason": "key missing" 和退出码 1。

无需密钥的检查

安全底线,已安装 Jev。在项目中运行;破坏性命令只是 JSON 载荷中的文本,不会被执行:

printf '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"},"cwd":"%s","session_id":"check"}' "$PWD" \
  | python3 .datarim-runtime/scripts/jev_hook.py claude PreToolUse      # 项目 Jev
# 宿主 Jev:将同一载荷通过管道传入  ~/.local/share/jev/bin/jev-hook claude PreToolUse

预期:"permissionDecision": "deny",原因为 Jev deterministic safety floor: recursive delete of a protected path。

问题 检查 预期
客户端会调用这些钩子吗? 在项目中使用某个客户端进行一次简短会话,然后运行 tail -n 3 .datarim-runtime/state/jev/ledger.jsonl 记录中会包含指明该客户端的 hook_delivery 记录。Floor 拒绝不会被记录。宿主 Jev 将其账本保存在 ~/.local/state/jev/projects/ 下。
Jev 是否已正确安装并限定作用域? jev doctor --agent=<client> 上述字段;该会话之后,native_agents_live 会将该客户端显示为 live
任务文件格式是否正确? bash .datarim-runtime/scripts/datarim-doctor.sh --root="$PWD",或在客户端中运行 /dr-doctor OK: datarim/ structure compliant

jev doctor 针对 Jev 给出答案(客户端、钩子注册、密钥文件、作用域、Codex 信任、钩子投递);datarim-doctor.sh 和 /dr-doctor 仅针对 datarim/ 任务文件的结构给出答案。

Codex 仅在你信任钩子后才会运行它们

使用 Jev 和 Codex 时,首次 Codex 会话会询问两次:先信任工作目录,然后 Hooks need review → Trust all and continue。拒绝是静默的:Codex 仍会将钩子列为活动状态,但从不运行它们。jev doctor --agent=codex 会根据 Codex 存储在 ~/.codex/config.toml 中的授权,将 codex_hook_trust 报告为 trusted、untrusted 或 not_measured。

宿主 Jev:针对 ~/.codex/hooks.json 中的钩子。如果其他工具重写了该文件,jev trust 只会重新授予对 Jev 自身钩子的信任;jevcodex 会自动执行此操作,除非设置了 JEV_NO_AUTO_TRUST=1。项目 Jev:针对 <project>/.codex/hooks.json 中的钩子;在项目内运行 jev trust 会重新授予对恰好这些钩子的信任,而 jevcodex 不会自动执行此操作。更改钩子命令的安装(例如解释器路径)会使 Codex 将这些钩子报告为已更改;jev trust 或 Codex 提示会再次批准它们。

7 更新

cd ~/src/datarim
git fetch --tags origin
git checkout "$(git describe --tags --abbrev=0 --match 'v*' origin/main)"   # 或:git checkout main && git pull
./update.sh --project "$PROJECT"   # 安装时所选的选项会被记住

update.sh 以单个事务运行同一个安装程序:先检查每个文件,拒绝覆盖你编辑过的任何内容,失败时回滚。

你的安装选择会被记住。 --with-jev、--host-jev、--context、--client、--expose-skills 会记录在 .datarim-runtime/installation.json 中,因此直接运行 update.sh --project 会保留它们,权限模式也保持不变。仅在需要更改时才传入选项:--without-jev 撤回项目的 Jev 钩子和 jev-config.json(密钥文件保留),--no-host-jev 恢复为项目钩子,--no-context 撤回嵌套仓库,--client 设置新的客户端列表。4.0 之前的安装没有记录客户端列表,会保留全部三个。

更新时保留:datarim/、config/credentials/、.datarim-runtime/state/(账本、开关和权限开关),以及 Jev 保持开启时的 .datarim-runtime/jev-config.json。.datarim-runtime/ 内的其他内容都会被替换,包括 .datarim-runtime/local/ 下的插件链接:更新后请运行 /dr-plugin sync。先前的运行时保留在 .datarim-runtime-previous/,更早的保留在 .datarim-runtime-backups/。主机 Jev:从更新后的检出目录重新运行 scripts/jev_host_install.py,使用相同的 --client 和 --datarim-project 选项;Codex 会保留其信任,因为钩子命令指向一个稳定的入口点。

从 Datarim 2.x 迁移
2.x 全局安装,并链接到各客户端的主目录。这些标志已不存在。仅移除 ~/.claude/{agents,skills,commands,templates,scripts,tests,dev-tools}(以及 Codex 和 Cursor 的对应目录)下解析到你的 Datarim 检出目录的链接,然后按上述方式逐项目安装。3.0 之前安装的项目会在其 AGENTS.md 中追加一段内容,并在 .gitignore 中追加规则;下一次安装或更新会移除这两者,并保持这些文件的其余部分不变。

8 卸载

~/src/datarim/install.sh --project "$PROJECT" --uninstall --dry-run
~/src/datarim/install.sh --project "$PROJECT" --uninstall

此操作会将安装更改过的文件恢复为安装前的内容,移除它添加的命令文件和钩子条目,并将运行时移动到 .datarim-uninstalled/。任务状态(datarim/)、密钥(config/credentials/)和运行时备份会保留,仍对 git 隐藏;不再需要时请自行删除。当 .datarim-uninstalled/ 存在时,第二次卸载会被拒绝。安装后你编辑过的文件会阻止卸载,直到你协调它们。

主机 Jev 没有卸载程序。jev off 会停止主机上所有 Jev API 调用。要移除它,请从客户端配置中删除 Jev 条目(命令中引用 ~/.local/share/jev/bin/jev-hook 的条目),然后删除 ~/.local/bin/{jev,jevclaude,jevcodex,jevcursor}、~/.local/share/jev/、~/.config/jev/(存放密钥)和 ~/.local/state/jev/(存放安装备份)。

出问题了?INSTALL.md 中的故障排除表将每条安装程序消息映射到其原因和修复方法。

9 你的第一个任务

前往已安装 Datarim 的项目并启动你的智能体(在 Codex、Cursor、Antigravity 和 MiniMax Code 中,让它运行 dr-init 技能):

cd /path/to/your/project
claude

# 在 Claude Code 中:
/dr-init 为设置页面添加深色模式切换

Datarim 会分析你的请求,确定复杂度(L1-L4),并在 datarim/ 中创建任务跟踪。

自 v2.7.0 起:当你的描述与待办列表中已存在的条目主题重叠时,步骤 2.5b 会给出软性提示,避免你为同一项工作创建第二个 ID。此提示不阻塞流程——由你在继续之前决定 重复 / 细化范围 / 正交。

10 遵循流水线

并非每个任务都需要全部 8 个阶段。Datarim 按复杂度进行路由:

L1
简单修复
init → do → archive
L2
标准功能
init → prd (含轻量调研) → plan → do → qa → archive
L3
复杂功能
init → prd (含完整调研) → plan → design → do → qa → compliance → archive
L4
大型项目
全部 8 个阶段 + consilium + 策略师评审

11 常用命令

/dr-help 列出全部命令
/dr-init 开始新任务
/dr-prd 需求 + 上下文调研
/dr-plan 详细实现计划
/dr-do 按计划实现(TDD)
/dr-qa 质量检查
/dr-verify 按需独立三层验证
/dr-archive 反思、归档并更新待办
/dr-write 创建内容
/dr-publish 发布到各平台
/dr-status 当前任务状态

12 项目结构

执行 /dr-init 后,你的项目将获得:

your-project/
├── .datarim-runtime/        # 此修订版本的框架(不纳入 git)
├── datarim/                 # 工作流状态(不纳入 git)
│   ├── tasks.md             # 进行中的任务
│   ├── backlog.md           # 待处理条目
│   ├── activeContext.md     # 当前焦点
│   ├── tasks/               # 任务文档
│   └── ...                  # prd/, creative/, reflection/, qa/, reports/, history/
└── documentation/
    └── archive/             # 已完成的任务(请提交)
        ├── web/
        ├── infrastructure/
        └── ...

datarim/ 是你的本地工作流;安装过程会通过 .git/info/exclude 将其与 .datarim-runtime/ 一并隐藏,而不会修改共享的 .gitignore。documentation/archive/ 是项目历史——请提交到 git。

Init-task 文件与问答日志(v2.9.0):/dr-init 会将你的原始提示逐字保存到 datarim/tasks/{ID}-init-task.md。此后每次澄清——智能体的提问与你的回答——都会以结构化的「Q&A by /dr-<stage>」块自动追加到该文件的 Append-log 中。若你未作答,智能体将依据最佳实践自主决策,并记录至少 50 字符的理由;评审阶段会对照实现逐一核验每项自主决策。

13 插件(v1.23.0+)

通过 /dr-plugin 以可选插件扩展 Datarim。每个插件是一个目录,包含 plugin.yaml 以及 {skills,agents,commands,templates}/ 子目录。启用后会在项目内的 .datarim-runtime/local/<cat>/<plugin-id>/ 下创建符号链接。

/dr-plugin list                              # 活动集
/dr-plugin enable /path/to/my-plugin     # 启用本地插件
/dr-plugin disable my-plugin              # 禁用
/dr-plugin sync                              # 协调运行时 ↔ 清单
/dr-plugin doctor [--fix]                    # 10 health checks

活动集清单:datarim/enabled-plugins.md。每次启用前均进行变更前快照/回滚。完整参考 — 命令页面 →

内置插件:dr-orchestrate、dr-jev-control、tdd-enforcement、dr-fleet-evolution 以及(v3.1.0+)controller-continuation —— 面向运行自有外部控制器的项目所提供的 /dr-continue-checkpoint worker 入口,仅限 Linux。它不是核心命令:核心仍保持 29 条命令。

14 网络暴露基线(v1.24.0+)

网络绑定目标的默认安全契约:docker-compose 端口、redis.conf 的 bind、postgresql.conf 的 listen_addresses、systemd .socket。默认公开即默认失守;新增的 network-exposure-baseline.md 技能以 TTL 受限的豁免机制将分层模型正式化。

Tier 0
unix socket / 不发布端口 —— 无需理由即可允许。
Tier 1
回环地址(127.0.0.1、::1)—— 允许;开发用 compose 的标准做法。
Tier 2
Tailscale CGNAT 100.64.0.0/10 —— 允许(按定义仅限网格内)。
Tier 3
0.0.0.0、[::]、公网 IP —— 要求内联 x-exposure-justification + x-exposure-expires(≤90 天)。

本地 pre-commit 检查:

dev-tools/network-exposure-check.sh \
  --compose docker-compose.yml \
  --redis-conf redis.conf \
  --postgres-conf postgresql.conf
# exit 0 — clean; exit 1 — violation

.github/workflows/ci.yml 中的可复用 CI 工作流:

jobs:
  network-exposure:
    uses: Arcanada-one/datarim/.github/workflows/network-exposure-lint.yml@<40-hex-commit>
    with:
      compose_paths: docker-compose.yml docker-compose.prod.yml
      datarim_ref: '<same-40-hex-commit>'

流水线命令(/dr-prd、/dr-plan、/dr-do、/dr-archive)在网络表面变更时自动加载该技能。分层门禁:P0 / 安全 / 基础设施 / 框架加固类任务 → hard_block;其余 → advisory_warn,可由操作员覆盖。

15 自主智能体运行规则(v2.6.0+)

当操作员需求不完整、复杂或含糊时,智能体不得停滞或进行不必要的升级上报。八条规范规则(FB-1..FB-8)在最高指令法则 1-5 之下定义自主行为。该授权位于使用方生态的 AGENTS.md 中(规范文本 + 审计标记);Datarim 仅提供机器可读的契约块。

FB-1
调研可用选项。
FB-2
对照最佳实践、安全性、可维护性进行比较。
FB-3
按专业角色进行议会审议(架构师 / 开发 / DevOps / 安全 / QA / PO)。
FB-4
选定一个选项,并将理由写入审计日志。
FB-5
在无需操作员参与的情况下执行可安全完成的部分。
FB-6
在不确定情况下使决策可逆。
FB-7
允许在测试后进行调整、回滚或重做。
FB-8
仅对真正阻塞性的问题升级上报。

机器可读的策略块:

dev-tools/rules/fb-rules.yaml
# rules: 8 × {rule_id, enforcement_layer, tier, default_action,
#               reversibility_required, audit_required, conflicts_with_law}
# hard_gated_actions: [prod_deploy, secret_rotation, irreversible_db_op,
#                      public_communication, finance_action, legal_action,
#                      force_push_main, git_history_delete, multi_user_visible_action,
#                      content_consilium_publish]

层级:最高指令(法则 1-5)> 自主智能体运行规则 > AAL 授权 > 项目特定授权。无论 FB-5 如何,hard_gated_actions 永不自动执行。加载器:dev-tools/fb-policy-loader.sh § load_fb_policy() / load_fb_hard_gates()(核心;dr-orchestrate 插件通过一层薄垫片调用它)。

D 文档:Diátaxis 分类法

每个由 Datarim 管理的仓库和产品站点都必须按照 Diátaxis 组织其文档:四个正交类别——tutorials/(学习)、how-to/(解决问题)、reference/(查阅)、explanation/(理解)。

documentation/
├── tutorials/        # learning-oriented
├── how-to/           # problem-solving (testing, deployment, gotchas)
├── reference/        # information-oriented (architecture, api, cli)
└── explanation/      # understanding-oriented (design, concepts)

封闭集合:faq、glossary、troubleshooting、examples、overview、samples——可映射,但绝不作为独立的顶层类型。与技术栈无关——SSG/CMS 的选择因项目而异。/dr-init create project 会在 documentation/ 下搭建此布局;/dr-optimize 会给出软性漂移警告,硬性 CI 门禁暂缓实施。